/ Hex Artifact Content
Login

Artifact c49acd2daa6e54110ab0cc607eb73ff32720a269:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
20c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
20d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
20e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
20f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2100: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2110: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2120: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2130: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2140: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2150: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2160: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2170: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2180: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2190: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
21a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
21b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
21c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
21d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
21e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
21f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2200: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2210: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2220: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2230: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2260: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2280: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2290: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
22a0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
22b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
22c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
22d0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
22e0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
22f0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2310: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2320: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2330: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
2340: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
2350: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2360: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2370: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2380: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2390: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
23a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
23b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
23c0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
23d0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
23e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23f0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2410: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2420: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2430: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
2440: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
2450: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2460: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2470: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2480: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2490: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
24a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
24b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
24c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
24d0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
24e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
24f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2500: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2510: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2520: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2530: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2540: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
2550: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2560: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2570: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2580: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2590: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
25a0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
25b0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
25c0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
25d0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
25e0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
25f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2600: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2610: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2620: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2630: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
2640: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
2650: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2660: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2670: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2680: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2690: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
26a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
26b0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
26c0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
26d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
26e0: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
26f0: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2700: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2710: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2720: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2730: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
2740: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2750: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2760: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2770: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2780: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2790: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
27a0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
27b0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
27c0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
27d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
27e0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
27f0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2800: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2810: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2820: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2830: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2840: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2850: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2860: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2870: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2880: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2890: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
28a0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
28b0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
28c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28d0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
28e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28f0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2900: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2910: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2920: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2940: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2950: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2960: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2970: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2980: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2990: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
29a0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
29b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
29c0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
29d0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
29e0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
29f0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a10: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a20: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2a40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2a50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2a60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2a70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2a80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2a90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2aa0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2ac0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2ad0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2b40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2b50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2b70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2b80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ba0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2bb0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2bc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2bd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2c60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2c70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2c80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2c90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2cb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2cc0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2cd0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ce0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2cf0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2d40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2d60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2d70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2d80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2d90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2da0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2db0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2dc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2dd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2de0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2df0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e20: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e40: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2e50: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2e60: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2e70: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2e90: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2ea0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2eb0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2ec0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2ed0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2ee0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2ef0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f00: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f10: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f30: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f50: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2f60: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2f70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f80: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2f90: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
2fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
2fb0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
2fc0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
2fd0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
2fe0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
2ff0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3000: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3010: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3020: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3030: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3060: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3070: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3080: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3090: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
30a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
30b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
30c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
30d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
30f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3100: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3110: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3120: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3130: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3150: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3160: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3170: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
31c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
31d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
31e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
31f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3200: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3210: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3220: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3230: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3240: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3250: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3260: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3270: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3280: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3290: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
32a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
32b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
32c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
32d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
32e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
32f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3300: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3310: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3320: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3330: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3340: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3360: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3370: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3380: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
3390: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
33a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
33b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
33c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
33d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
33f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3400: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3410: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3430: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3440: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3450: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3460: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3470: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3480: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
34a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
34b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
34c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
34d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
34e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
34f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3500: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3510: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3530: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3540: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3550: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3580: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
35b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
35c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
35d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
35e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
35f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3600: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3610: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3620: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3630: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3640: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3650: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3660: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3670: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3680: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3690: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
36a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
36b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
36c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
36d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
36e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
36f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3700: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3710: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3720: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3740: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3750: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3760: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3770: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3780: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3790: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
37a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
37b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
37c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
37d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
37e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
37f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3800: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3810: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3820: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3830: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3840: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3850: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3860: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3870: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3880: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3890: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
38a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
38b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
38c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
38e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
38f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3900: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3910: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3920: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3950: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3960: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3970: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3980: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3990: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
39a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
39b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
39c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
39d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
39e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
39f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3a40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3a50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3a60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3a70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3a80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3a90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3aa0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3ac0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3ad0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ae0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3af0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3b40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3b50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3b60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3b70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3b80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3b90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ba0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3bb0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3bc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3bd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3be0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3c40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3c50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3c60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3c80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3c90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ca0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3cb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3cc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3cd0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ce0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3d40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3d50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3d60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3d70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3d80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3d90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3da0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3db0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3dc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3dd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3de0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3df0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3e40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3e50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3e70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3e80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3ea0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3eb0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3ec0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ef0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f00: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f30: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3f40: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3f50: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3f60: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3f70: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3f80: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fa0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3fb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3fc0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3fd0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ff0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4000: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4010: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4050: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4060: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4070: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4080: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4090: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
40d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
40e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
40f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4120: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4140: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4150: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4160: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4170: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4180: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4190: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
41e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
41f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4200: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4210: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4220: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4240: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4250: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4260: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4270: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4280: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4290: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
42a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
42b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
42d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
42e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
42f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4300: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4310: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4320: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4330: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4340: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4350: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4360: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4370: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4380: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4390: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
43a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
43b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
43c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
43f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4400: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4430: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4450: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4470: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4480: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
44b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
44c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
44d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
44e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
44f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4500: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4510: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4520: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4540: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4550: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4560: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4570: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4590: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
45a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
45b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
45e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
45f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4600: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4610: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4620: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4630: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4640: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4650: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4660: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4680: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4690: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
46a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
46c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
46d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
46e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4700: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4710: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4720: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4730: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4740: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4750: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4760: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4770: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4780: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4790: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
47a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
47b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
47d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
47e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
47f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4800: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4810: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4820: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4840: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4850: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4860: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4890: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
48a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
48b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
48c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
48d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
48e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
48f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4900: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4910: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4920: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4930: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4950: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4960: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4970: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
49b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
49c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
49d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
49e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49f0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4a40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4a50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4a60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4a70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4a80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4a90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4aa0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ac0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ad0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ae0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4af0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4b40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4b70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4b80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4b90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4ba0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4bb0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4bc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4bd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4be0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4bf0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4c40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4c50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4c60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4c70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4c80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4c90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ca0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4cb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4cc0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4cd0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4ce0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4cf0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d00: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d10: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d30: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4d40: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4d50: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4d60: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4d70: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4db0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4dc0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4dd0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4de0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4df0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e00: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e10: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e20: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e30: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e50: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4e60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4e80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4e90: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4ea0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4eb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4ed0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4ee0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ef0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f50: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f70: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4f90: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4fa0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fe0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4ff0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5000: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5010: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5020: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5030: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
50b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
50f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5100: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5110: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5120: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5180: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5190: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
51a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
51f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5200: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5210: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5220: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5250: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5260: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
53d0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5450: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
54d0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
54e0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5510: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5520: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5550: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5560: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5590: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
55a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
55b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
55d0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
55e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
55f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5600: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5610: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5620: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5630: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5650: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5660: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5670: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5690: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
56a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
56b0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
56d0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
56e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
56f0: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5720: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5730: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5760: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5770: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
57a0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
57b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
57d0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
57e0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
57f0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5820: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5830: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5860: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5870: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5880: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58a0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
58b0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
58c0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
58d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
58f0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5930: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5950: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5970: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5980: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5990: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59b0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59d0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
59e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a00: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a40: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a60: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a80: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5a90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5aa0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ac0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5ad0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5ae0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b10: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b20: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5b40: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5b50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5b60: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5b80: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ba0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5bc0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5bd0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5be0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5bf0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c00: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c10: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5c40: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5c50: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5c60: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5c70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5c80: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ca0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5cb0: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5cc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5cd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5cf0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d00: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5d40: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5d50: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5d60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d70: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5d90: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5da0: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5db0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5dc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5dd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5de0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5df0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e10: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e20: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e60: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5ea0: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5eb0: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5ef0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f00: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f40: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5f50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5f70: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5f80: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5f90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5fb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5fc0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
5fd0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5ff0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6000: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6010: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6020: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6030: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
6040: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6050: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6070: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6080: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6090: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
60b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
60c0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
60d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
60e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
60f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6100: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6110: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6120: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6130: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6150: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6160: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6170: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6180: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
61a0: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
61b0: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
61c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6200: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6210: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6220: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6240: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6260: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6270: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6280: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6290: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
62a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
62b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
62c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
62d0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
62e0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
62f0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6300: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6310: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6320: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6330: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6340: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6350: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6360: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6370: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
63b0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
63c0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
63d0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
63e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
63f0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6400: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6410: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6420: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6430: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6440: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6450: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6460: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6470: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6480: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6490: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
64a0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
64b0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
64c0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
64d0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
64e0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
64f0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6500: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6510: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6520: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6530: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6550: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6560: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6570: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6580: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6590: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
65a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
65b0: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
65d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6600: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6610: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6620: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6630: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
6640: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6650: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6660: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6670: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6680: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6690: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
66a0: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
66b0: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
66c0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
66d0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6700: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6710: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6720: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6730: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6740: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6750: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6760: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6770: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6780: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6790: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
67a0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
67b0: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
67c0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
67d0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
67e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67f0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6810: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6830: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6840: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6860: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6870: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6880: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
68a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
68e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6900: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6910: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6920: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6940: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6950: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6970: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6980: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6990: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
69a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69b0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
69c0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
69d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
69f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a30: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6a50: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a60: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a80: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6a90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6aa0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6ac0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6ad0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6af0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b00: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b10: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6b40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6b50: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6b60: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6b70: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6b80: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6bf0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c30: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c70: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6c80: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6c90: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6ca0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6cb0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6cc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6cd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6ce0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6cf0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d20: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d30: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6d50: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6d60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6d70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6d80: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6d90: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6da0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6db0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6dc0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6dd0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6de0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6df0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e10: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e20: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e30: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6e40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6e50: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6e70: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6e80: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6e90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6ea0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6eb0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6ec0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6ed0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ef0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f00: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f10: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f20: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f30: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6f40: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6f50: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6f60: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6f70: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6f80: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6f90: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6fa0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6fb0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6fc0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6fe0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ff0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7000: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7010: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7020: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7030: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7040: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7050: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7060: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7070: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7080: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7090: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
70a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70b0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
70c0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
70d0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
70e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70f0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7100: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7110: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7120: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7130: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7140: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7150: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7160: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7170: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7180: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7190: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
71a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71b0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
71c0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
71e0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
71f0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7200: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7210: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7220: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7240: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7250: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7260: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7270: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7280: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7290: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
72a0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
72b0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
72c0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
72d0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
72e0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
72f0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7300: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7310: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7320: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7330: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7340: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7350: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7360: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7370: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7380: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7390: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
73a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
73b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
73c0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
73d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
73e0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
73f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7400: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7410: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7420: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7440: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7450: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7460: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7470: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7480: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7490: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
74a0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
74b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
74c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
74d0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
74e0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
74f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7500: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7510: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7520: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7530: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7540: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7550: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7560: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7570: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7580: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7590: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
75a0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
75d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
75e0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7600: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7610: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7620: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7640: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7650: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7660: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7680: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7690: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
76a0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
76b0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
76c0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
76d0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
76e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76f0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7710: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7720: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7730: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7740: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7770: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7780: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7790: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
77a0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
77b0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
77c0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
77d0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
77e0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
77f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7800: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7810: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7820: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7830: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7840: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7850: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7860: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7870: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7880: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7890: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
78a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
78b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
78c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
78d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
78f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7900: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7930: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7940: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7950: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7960: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7970: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7980: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7990: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
79a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
79b0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
79c0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
79d0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
79e0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
79f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a00: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a10: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a20: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a30: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7a40: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7a50: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7a60: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7a70: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7a80: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7a90: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7aa0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7ab0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7ac0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7ad0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7ae0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7af0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b00: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b10: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b20: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b30: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7b40: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7b50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7b60: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7b70: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7b80: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7b90: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7ba0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7bb0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7bc0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7bd0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7be0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7bf0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7c40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7c50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7c60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7c70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7c80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7c90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7ca0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7cb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7cc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7cd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7ce0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7cf0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d00: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d10: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d20: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d30: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7d40: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7d50: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7d60: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7d70: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7d80: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d90: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7da0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7db0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7dc0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7dd0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7de0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7df0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e00: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e10: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e20: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e50: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e70: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e80: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7ea0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7eb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7ec0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7ed0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ee0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ef0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f00: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f10: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f20: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f30: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f40: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f50: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f60: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f70: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f90: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7fa0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7fb0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7fc0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7fd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ff0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8090: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
80a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80b0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
80c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80d0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8140: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8150: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8160: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8170: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8180: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8190: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
81a0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
81c0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
81d0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81e0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81f0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8200: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8210: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8220: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8230: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8240: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8250: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8260: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8270: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8280: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8290: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
82a0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
82b0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
82c0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
82d0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82e0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8300: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8320: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8330: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8340: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8350: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8360: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8370: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8380: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8390: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
83a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
83b0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
83c0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
83d0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83e0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83f0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8400: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8410: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8420: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8430: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8440: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8450: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8470: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8480: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8490: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
84a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
84b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84c0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
84d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84f0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8500: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8510: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8530: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8540: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8550: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8560: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8570: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8580: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
85c0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
85d0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85e0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85f0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8600: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8610: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8620: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8630: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8640: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8650: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8690: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
86a0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
86b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86e0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8700: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8710: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8730: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8740: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8760: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8770: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8780: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8790: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
87c0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
87d0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87e0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8800: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8810: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8820: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8850: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8860: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8870: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8880: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8890: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
88a0: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
88d0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88e0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88f0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8960: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8970: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8980: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8990: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
89a0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
89b0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
89c0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
89d0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
89e0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
89f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a10: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a20: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8a40: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8a70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a90: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8aa0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8ac0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ad0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8ae0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8af0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8b00: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8b10: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8b20: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8b30: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8b50: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8b60: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8b80: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8b90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8ba0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8bb0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8bc0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8bd0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8be0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8bf0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8c00: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8c10: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8c20: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8c30: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8c40: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8c50: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8c60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8c70: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8c80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8c90: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8ca0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8cb0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8cc0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8cd0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8ce0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8cf0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8d00: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8d10: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8d20: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8d30: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8d40: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8d50: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8d60: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8d70: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8d80: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8d90: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8da0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8db0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8dc0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8dd0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8de0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8df0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8e00: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8e10: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e20: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8e30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8e40: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8e50: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8e60: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8e70: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8e80: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8e90: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ea0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8eb0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8ec0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8ed0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8ee0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8ef0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8f00: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8f10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8f20: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8f30: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8f40: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8f50: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8f60: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8f70: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8f80: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8f90: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8fa0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8fb0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8fc0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8fd0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8fe0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8ff0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9000: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9010: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9020: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9030: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9040: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
9050: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9060: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9070: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9080: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9090: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
90a0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
90b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
90c0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
90d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
90e0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
90f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9100: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9110: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9120: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9130: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9140: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9150: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9170: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9180: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9190: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
91a0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
91b0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
91c0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
91d0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
91e0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
91f0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9200: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9210: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9220: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9230: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9240: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9250: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9260: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9270: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9280: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9290: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
92a0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
92b0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
92c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
92d0: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
92e0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
92f0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9300: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9310: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9320: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9330: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9340: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9350: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9360: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9370: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9380: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9390: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
93a0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
93b0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
93c0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
93d0: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
93e0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
93f0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9400: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9410: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9420: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9430: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9440: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9450: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9460: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9470: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9480: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9490: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
94a0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
94b0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
94c0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
94d0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
94e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
94f0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9500: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9510: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9520: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9530: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9540: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9550: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9560: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9570: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9580: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9590: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
95a0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
95b0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
95c0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
95d0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
95e0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
95f0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9600: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9610: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9620: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9630: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9640: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9650: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9660: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9670: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9680: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9690: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
96a0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
96b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
96c0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96d0: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
96e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
96f0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9700: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9710: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9720: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9730: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9740: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9750: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9760: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9770: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9780: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9790: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
97a0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
97b0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
97c0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
97d0: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
97e0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
97f0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9800: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9810: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9820: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9830: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9840: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9850: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9860: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9870: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9880: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9890: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
98a0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
98b0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
98c0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
98d0: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
98e0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
98f0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9900: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9910: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9920: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9930: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9940: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9950: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9960: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9970: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9980: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9990: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
99a0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
99b0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
99c0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
99d0: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
99e0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
99f0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9a00: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9a10: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9a20: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9a30: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9a40: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9a50: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9a60: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9a70: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9a80: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9a90: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9aa0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9ab0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9ac0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9ad0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ae0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9af0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9b00: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9b10: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9b20: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9b30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9b40: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9b50: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9b60: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9b70: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9b80: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9b90: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9ba0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9bb0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9bc0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9bd0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9be0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9bf0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9c00: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9c10: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9c20: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9c30: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9c40: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9c50: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9c60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9c70: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9c80: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9c90: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9ca0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9cb0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9cc0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9cd0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9ce0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9cf0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9d00: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9d10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9d20: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9d30: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9d40: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9d50: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9d60: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9d70: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9d80: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9d90: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9da0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9db0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9dc0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9dd0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9de0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9df0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9e00: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9e10: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9e20: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9e30: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9e40: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9e50: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9e60: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9e70: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e80: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e90: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ea0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9eb0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9ec0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ed0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9ee0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9ef0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9f00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9f10: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9f20: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9f30: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9f40: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9f50: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9f60: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9f70: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9f80: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9f90: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9fa0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9fb0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9fc0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9fd0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9fe0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9ff0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a010: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a020: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a030: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a040: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a050: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a060: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a070: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a080: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a090: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a0a0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a0b0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a0c0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a0d0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a0e0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a0f0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a100: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a110: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a120: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a130: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a140: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a150: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a160: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a170: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a180: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a190: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a1a0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a1b0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a1c0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a1d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a1e0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a1f0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a200: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a210: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a220: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a230: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a240: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a250: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a270: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a280: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a290: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a2a0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a2b0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a2c0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a2d0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a2e0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a2f0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a300: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a310: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a320: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a330: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a340: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a350: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a360: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a370: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a380: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a390: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a3a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a3b0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a3c0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a3d0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a3e0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a3f0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a400: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a410: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a420: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a430: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a440: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a450: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a460: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a470: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a480: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a490: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a4a0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a4b0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a4c0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a4d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a4e0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a4f0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a500: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a510: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a520: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a530: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a540: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a550: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a560: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a570: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a580: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a590: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a5a0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a5b0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a5c0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a5d0: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a5e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a5f0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a600: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a610: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a620: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a630: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a640: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a650: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a660: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a670: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a680: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a690: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a6a0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a6b0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a6c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a6d0: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a6e0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a6f0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a700: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a710: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a720: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a730: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a740: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a750: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a760: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a770: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a780: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a790: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a7a0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a7b0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a7c0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a7d0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a7e0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a7f0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a800: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a810: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a820: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a840: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a850: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a860: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a870: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a880: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a890: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a8a0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a8b0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a8c0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a8d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a8e0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a8f0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a900: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a910: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a920: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a930: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a940: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a950: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a960: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a970: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a980: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a990: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a9a0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a9b0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a9c0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a9d0: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a9e0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a9f0: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
aa00: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
aa10: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
aa20: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
aa30: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
aa40: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
aa50: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
aa60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa70: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aa80: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
aa90: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
aaa0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
aab0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
aac0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
aad0: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
aae0: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
aaf0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
ab00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ab10: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ab20: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
ab30: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ab40: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
ab50: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
ab60: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
ab70: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
ab80: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
ab90: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
aba0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
abb0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
abc0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
abd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
abe0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
abf0: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ac00: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ac10: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
ac20: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
ac30: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
ac40: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
ac50: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
ac60: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
ac70: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
ac80: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
ac90: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
aca0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
acb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
acc0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
acd0: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ace0: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
acf0: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ad00: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ad10: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
ad20: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
ad30: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
ad40: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
ad50: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ad60: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
ad70: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ad80: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ad90: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ada0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
adb0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
adc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
add0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ade0: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
adf0: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ae00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ae10: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ae20: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
ae30: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
ae40: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
ae50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ae60: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
ae70: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ae80: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ae90: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
aea0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
aeb0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
aec0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
aed0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
aee0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
aef0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
af00: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
af10: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
af20: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
af30: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
af40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
af50: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
af60: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
af70: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
af80: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
af90: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
afa0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
afb0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
afc0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
afd0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
afe0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
aff0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b000: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
b010: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
b020: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
b030: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
b040: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
b050: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
b060: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b070: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b080: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b090: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b0a0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b0b0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b0d0: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b0e0: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b0f0: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b110: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b120: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b130: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b140: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b150: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b160: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b170: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b180: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b190: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b1a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b1b0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b1c0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b1d0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b1e0: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b1f0: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b200: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b210: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b220: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b230: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b240: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b250: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b260: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b270: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b280: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b290: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b2a0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b2b0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b2c0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b2d0: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b2e0: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b2f0: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b300: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b310: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b320: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b330: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b340: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b350: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b360: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b370: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b380: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b390: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b3a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b3b0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b3c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b3d0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b3e0: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b3f0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b400: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b410: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b420: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b430: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b440: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b450: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b460: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b470: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b480: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b490: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b4a0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b4b0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b4c0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b4d0: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b4f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b500: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
b510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b520: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
b530: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
b540: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
b550: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
b560: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
b570: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
b580: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
b590: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
b5a0: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
b5b0: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
b5c0: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
b5d0: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
b5e0: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
b5f0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
b600: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
b610: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
b620: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
b630: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b640: 43 4e 54 4c 5f 5a 49 50 56 46 53 5f 50 41 47 45  CNTL_ZIPVFS_PAGE
b650: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
b660: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5f  TE_FCNTL_ZIPVFS_
b670: 50 41 47 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  PAGER] opcode is
b680: 20 75 73 65 64 20 62 79 20 74 68 65 20 4f 54 41   used by the OTA
b690: 20 65 78 74 65 6e 73 69 6f 6e 20 77 68 65 6e 0a   extension when.
b6a0: 2a 2a 20 75 70 64 61 74 69 6e 67 20 61 20 7a 69  ** updating a zi
b6b0: 70 76 66 73 20 64 61 74 61 62 61 73 65 2e 0a 2a  pvfs database..*
b6c0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
b6d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b6e0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
b6f0: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
b700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
b710: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b720: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
b730: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
b740: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
b750: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
b760: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
b770: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
b780: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
b790: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
b7a0: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
b7b0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
b7c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
b7d0: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
b7e0: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
b7f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
b800: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
b810: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
b820: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
b830: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
b840: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
b850: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b860: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
b870: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
b880: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
b890: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
b8a0: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
b8b0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
b8c0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
b8d0: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
b8e0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
b8f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b900: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b910: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
b920: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
b930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b940: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
b950: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
b960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b970: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b980: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
b990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b9a0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b9b0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64             16.#d
b9c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b9d0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  TL_MMAP_SIZE    
b9e0: 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65            18.#de
b9f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ba00: 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20  L_TRACE         
ba10: 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66           19.#def
ba20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ba30: 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20  _HAS_MOVED      
ba40: 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69          20.#defi
ba50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ba60: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
ba70: 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e         21.#defin
ba80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
ba90: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20  OMMIT_PHASETWO  
baa0: 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65        22.#define
bab0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
bac0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20  N32_SET_HANDLE  
bad0: 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20       23.#define 
bae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
baf0: 56 46 53 5f 50 41 47 45 52 20 20 20 20 20 20 20  VFS_PAGER       
bb00: 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53      24.#define S
bb10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 54 41 20  QLITE_FCNTL_OTA 
bb20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bb30: 20 20 20 32 35 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     25../*.** CAP
bb40: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
bb50: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
bb60: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
bb70: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
bb80: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
bb90: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
bba0: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
bbb0: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
bbc0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
bbd0: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
bbe0: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
bbf0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
bc00: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
bc10: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
bc20: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
bc30: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
bc40: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
bc50: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
bc60: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
bc70: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
bc80: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
bc90: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
bca0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
bcb0: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
bcc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
bcd0: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
bce0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
bcf0: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
bd00: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
bd10: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
bd20: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
bd30: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
bd40: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
bd50: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
bd60: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
bd70: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
bd80: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
bd90: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
bda0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
bdb0: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
bdc0: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
bdd0: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
bde0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
bdf0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
be00: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
be10: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
be20: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
be30: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
be40: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
be50: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
be60: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
be70: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
be80: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
be90: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
bea0: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
beb0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
bec0: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
bed0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
bee0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
bef0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
bf00: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
bf10: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
bf20: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
bf30: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
bf40: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
bf50: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
bf60: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
bf70: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
bf80: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
bf90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
bfa0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
bfb0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
bfc0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
bfd0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
bfe0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
bff0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
c000: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
c010: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
c020: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
c030: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
c040: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
c050: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
c060: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c070: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
c080: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
c090: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
c0a0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
c0b0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
c0c0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
c0d0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
c0e0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
c0f0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
c100: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
c110: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
c120: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
c130: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
c140: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
c150: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
c160: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
c170: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
c180: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
c190: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c1a0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
c1b0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
c1c0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
c1d0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
c1e0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
c1f0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
c200: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
c210: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
c220: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
c230: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c240: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
c250: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
c260: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c270: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
c280: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
c290: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
c2a0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
c2b0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
c2c0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
c2d0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
c2e0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
c2f0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
c300: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
c310: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
c320: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
c330: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
c340: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c350: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c360: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
c370: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
c380: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
c390: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
c3a0: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
c3b0: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
c3c0: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
c3d0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
c3e0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
c3f0: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
c400: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
c410: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
c420: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
c430: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
c440: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
c450: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
c460: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
c470: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
c480: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
c490: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
c4a0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
c4b0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
c4c0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
c4d0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
c4e0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
c4f0: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
c500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
c510: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
c520: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
c530: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
c540: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
c550: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
c560: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
c570: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
c580: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c590: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
c5a0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
c5b0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
c5c0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
c5d0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
c5e0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
c5f0: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
c600: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c610: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
c620: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
c630: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
c640: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
c650: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
c660: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c670: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
c680: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c690: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
c6a0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
c6b0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
c6c0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
c6d0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
c6e0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
c6f0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
c700: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
c710: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
c720: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
c730: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
c740: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
c750: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
c760: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
c770: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
c780: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
c790: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
c7a0: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
c7b0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
c7c0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
c7d0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
c7e0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
c7f0: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
c800: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
c810: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
c820: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
c830: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
c840: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
c850: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
c860: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
c870: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
c880: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c890: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
c8a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
c8b0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
c8c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c8d0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
c8e0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c8f0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
c900: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c910: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
c920: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c930: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
c940: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c950: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
c960: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c970: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c980: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
c990: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
c9a0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
c9b0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
c9c0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
c9d0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
c9e0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
c9f0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
ca00: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
ca10: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
ca20: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
ca30: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
ca40: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
ca50: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
ca60: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
ca70: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
ca80: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
ca90: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
caa0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
cab0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
cac0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
cad0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
cae0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
caf0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
cb00: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
cb10: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
cb20: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
cb30: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
cb40: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
cb50: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
cb60: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
cb70: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
cb80: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
cb90: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
cba0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
cbb0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
cbc0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
cbd0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
cbe0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
cbf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
cc00: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cc10: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
cc20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
cc30: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
cc40: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
cc50: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
cc60: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
cc70: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
cc80: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
cc90: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
cca0: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
ccb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
ccc0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
ccd0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
cce0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
ccf0: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
cd00: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
cd10: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
cd20: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
cd30: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
cd40: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
cd50: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
cd60: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
cd70: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
cd80: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
cd90: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
cda0: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
cdb0: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
cdc0: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
cdd0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
cde0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
cdf0: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
ce00: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
ce10: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
ce20: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
ce30: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
ce40: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
ce50: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
ce60: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
ce70: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
ce80: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
ce90: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
cea0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
ceb0: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
cec0: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
ced0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
cee0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
cef0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
cf00: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
cf10: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
cf20: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
cf30: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
cf40: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
cf50: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
cf60: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
cf70: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
cf80: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
cf90: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
cfa0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
cfb0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
cfc0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
cfd0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
cfe0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
cff0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
d000: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
d010: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
d020: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d030: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
d040: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
d050: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d060: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
d070: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
d080: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
d090: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
d0a0: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
d0b0: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
d0c0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d0d0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
d0e0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
d0f0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
d100: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
d110: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
d120: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
d130: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
d140: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d150: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
d160: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
d170: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
d180: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
d190: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
d1a0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
d1b0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
d1c0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d1d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
d1e0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
d1f0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
d200: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
d210: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d220: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
d230: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
d240: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
d250: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
d260: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
d270: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
d280: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d290: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
d2a0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
d2b0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
d2c0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
d2d0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
d2e0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
d2f0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
d300: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d310: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
d320: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
d330: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
d340: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d350: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
d360: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
d370: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
d380: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
d390: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
d3a0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
d3b0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
d3c0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
d3d0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
d3e0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
d3f0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
d400: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
d410: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
d420: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
d430: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
d440: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
d450: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
d460: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
d470: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
d480: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
d490: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
d4a0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
d4b0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
d4c0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
d4d0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
d4e0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
d4f0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
d500: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
d510: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
d520: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
d530: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
d540: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
d550: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
d560: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
d570: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
d580: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
d590: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
d5a0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
d5b0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
d5c0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
d5d0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
d5e0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
d5f0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
d600: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
d610: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
d620: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
d630: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
d640: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
d650: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
d660: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
d670: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
d680: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
d690: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
d6a0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
d6b0: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
d6c0: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
d6d0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
d6e0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
d6f0: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
d700: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
d710: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
d720: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
d730: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
d740: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
d750: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
d760: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
d770: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
d780: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
d790: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
d7a0: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
d7b0: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
d7c0: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
d7d0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
d7e0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
d7f0: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
d800: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
d810: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
d820: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
d830: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
d840: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
d850: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
d860: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
d870: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
d880: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
d890: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
d8a0: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
d8b0: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
d8c0: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
d8d0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
d8e0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
d8f0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
d900: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
d910: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
d920: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
d930: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
d940: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
d950: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
d960: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
d970: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
d980: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
d990: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
d9a0: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
d9b0: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
d9c0: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
d9d0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
d9e0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
d9f0: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
da00: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
da10: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
da20: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
da30: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
da40: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
da50: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
da60: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
da70: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
da80: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
da90: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
daa0: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
dab0: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
dac0: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
dad0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
dae0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
daf0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
db00: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
db10: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
db20: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
db30: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
db40: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
db50: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
db60: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
db70: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
db80: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
db90: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
dba0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
dbb0: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
dbc0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
dbd0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
dbe0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
dbf0: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
dc00: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
dc10: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
dc20: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
dc30: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
dc40: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
dc50: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
dc60: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
dc70: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
dc80: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
dc90: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
dca0: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
dcb0: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
dcc0: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
dcd0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
dce0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
dcf0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
dd00: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
dd10: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
dd20: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
dd30: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
dd40: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
dd50: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
dd60: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dd70: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
dd80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
dd90: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
dda0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
ddb0: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
ddc0: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
ddd0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
dde0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
ddf0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
de00: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
de10: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
de20: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
de30: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
de40: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
de50: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
de60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
de70: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
de80: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
de90: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
dea0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
deb0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
dec0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
ded0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
dee0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
def0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
df00: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
df10: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
df20: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
df30: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
df40: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
df50: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
df60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
df70: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
df80: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
df90: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
dfa0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
dfb0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
dfc0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
dfd0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
dfe0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
dff0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
e000: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
e010: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
e020: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
e030: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
e040: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e050: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e060: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
e070: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e080: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
e090: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
e0a0: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
e0b0: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
e0c0: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
e0d0: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
e0e0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
e0f0: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
e100: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
e110: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e120: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e130: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
e140: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e150: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
e160: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
e170: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
e180: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
e190: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
e1a0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e1b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e1c0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e1d0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
e1e0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e1f0: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
e200: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e210: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e220: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
e230: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
e240: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e250: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e260: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
e270: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e280: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e290: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
e2a0: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
e2b0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
e2c0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
e2d0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
e2e0: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
e2f0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
e300: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
e310: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
e320: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
e330: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
e340: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
e350: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
e360: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e370: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e380: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
e390: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
e3a0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
e3b0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
e3c0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
e3d0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
e3e0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
e3f0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
e400: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
e410: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e420: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
e430: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e440: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
e450: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e460: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
e470: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
e480: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
e490: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e4a0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
e4b0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e4c0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
e4d0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
e4e0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
e4f0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
e500: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
e510: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
e520: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
e530: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
e540: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
e550: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
e560: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e570: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
e580: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
e590: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
e5a0: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
e5b0: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
e5c0: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
e5d0: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
e5e0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
e5f0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
e600: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
e610: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
e620: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
e630: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
e640: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
e650: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
e660: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
e670: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
e680: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
e690: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
e6a0: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
e6b0: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
e6c0: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
e6d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
e6e0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
e6f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
e700: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
e710: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
e720: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
e730: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
e740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
e750: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
e760: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
e770: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
e780: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
e790: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
e7a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
e7b0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
e7c0: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
e7d0: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
e7e0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
e7f0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
e800: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
e810: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
e820: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
e830: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
e840: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
e850: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
e860: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
e870: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
e880: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
e890: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
e8a0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e8b0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e8c0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
e8d0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
e8e0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e8f0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e900: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
e910: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e920: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
e930: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e940: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
e950: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
e960: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
e970: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
e980: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
e990: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
e9a0: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
e9b0: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
e9c0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
e9d0: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
e9e0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
e9f0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
ea00: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
ea10: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
ea20: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
ea30: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
ea40: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
ea50: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
ea60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ea70: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
ea80: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
ea90: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
eaa0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
eab0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
eac0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
ead0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
eae0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
eaf0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
eb00: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
eb10: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
eb20: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
eb30: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
eb40: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
eb50: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
eb60: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
eb70: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
eb80: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
eb90: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
eba0: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
ebb0: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
ebc0: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
ebd0: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
ebe0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
ebf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ec00: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
ec10: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
ec20: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
ec30: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
ec40: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ec50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ec60: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
ec70: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
ec80: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
ec90: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
eca0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
ecb0: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
ecc0: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
ecd0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
ece0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ecf0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
ed00: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
ed10: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
ed20: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
ed30: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
ed40: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
ed50: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
ed60: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
ed70: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
ed80: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
ed90: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
eda0: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
edb0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
edc0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
edd0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ede0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
edf0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
ee00: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
ee10: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
ee20: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
ee30: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
ee40: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
ee50: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
ee60: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ee70: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
ee80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
ee90: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
eea0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
eeb0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
eec0: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
eed0: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
eee0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
eef0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
ef00: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
ef10: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
ef20: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
ef30: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
ef40: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
ef50: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
ef60: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
ef70: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
ef80: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
ef90: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
efa0: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
efb0: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
efc0: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
efd0: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
efe0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
eff0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
f000: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
f010: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
f020: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
f030: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
f040: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
f050: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f060: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f070: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f080: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
f090: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
f0a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
f0b0: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
f0c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f0d0: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
f0e0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
f0f0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
f100: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
f110: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
f120: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
f130: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
f140: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
f150: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
f160: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
f170: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
f180: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
f190: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
f1a0: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
f1b0: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
f1c0: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
f1d0: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
f1e0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
f1f0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
f200: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
f210: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
f220: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
f230: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f240: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f250: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
f260: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
f270: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
f280: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
f290: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f2a0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
f2b0: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
f2c0: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
f2d0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
f2e0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
f2f0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
f300: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
f310: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
f320: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
f330: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
f340: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
f350: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f360: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
f370: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
f380: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
f390: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f3a0: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
f3b0: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
f3c0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
f3d0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
f3e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f3f0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
f400: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
f410: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
f420: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
f430: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
f440: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
f450: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
f460: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
f470: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
f480: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
f490: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
f4a0: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
f4b0: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
f4c0: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
f4d0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f4e0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
f4f0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
f500: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
f510: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
f520: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
f530: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f540: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
f550: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
f560: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
f570: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
f580: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
f590: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
f5a0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
f5b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
f5c0: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
f5d0: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
f5e0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
f5f0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
f600: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
f610: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f620: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
f630: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
f640: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
f650: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
f660: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
f670: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
f680: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
f690: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
f6a0: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
f6b0: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
f6c0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f6d0: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
f6e0: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
f6f0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
f700: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
f710: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
f720: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
f730: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f740: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
f750: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
f760: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
f770: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
f780: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
f790: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
f7a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f7b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
f7c0: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
f7d0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
f7e0: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
f7f0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
f800: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
f810: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
f820: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
f830: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
f840: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
f850: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f860: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
f870: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
f880: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
f890: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
f8a0: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
f8b0: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
f8c0: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
f8d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f8e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
f8f0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f900: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
f910: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
f920: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
f930: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
f940: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
f950: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
f960: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
f970: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f980: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
f990: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
f9a0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f9b0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
f9c0: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
f9d0: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
f9e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
f9f0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
fa00: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
fa10: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
fa20: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
fa30: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
fa40: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
fa50: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
fa60: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
fa70: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
fa80: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
fa90: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
faa0: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
fab0: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
fac0: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
fad0: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
fae0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
faf0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
fb00: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
fb10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
fb20: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
fb30: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
fb40: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
fb50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
fb60: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
fb70: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
fb80: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
fb90: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
fba0: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
fbb0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
fbc0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
fbd0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
fbe0: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
fbf0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
fc00: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
fc10: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
fc20: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
fc30: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
fc40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fc50: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
fc60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
fc70: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
fc80: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
fc90: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
fca0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
fcb0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
fcc0: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
fcd0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
fce0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
fcf0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
fd00: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
fd10: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
fd20: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
fd30: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
fd40: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
fd50: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
fd60: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
fd70: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
fd80: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
fd90: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
fda0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
fdb0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
fdc0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
fdd0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
fde0: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
fdf0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
fe00: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
fe10: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
fe20: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
fe30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fe40: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
fe50: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
fe60: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
fe70: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
fe80: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
fe90: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
fea0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
feb0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
fec0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
fed0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
fee0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
fef0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
ff00: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
ff10: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
ff20: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
ff30: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
ff40: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
ff50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff60: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
ff70: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
ff80: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
ff90: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
ffa0: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
ffb0: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
ffc0: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
ffd0: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
ffe0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
fff0: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
10000 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
10010 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
10020 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
10030 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
10040 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
10050 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
10060 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
10070 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
10080 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
10090 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
100a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
100b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
100c0 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
100d0 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
100e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
100f0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
10100 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
10110 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
10120 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
10130 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
10140 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
10150 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
10160 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10170 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
10180 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
10190 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
101a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
101b0 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
101c0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
101d0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
101e0 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
101f0 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
10200 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
10210 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
10220 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
10230 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
10240 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10250 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
10260 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
10270 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
10280 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10290 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
102a0 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
102b0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
102c0 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
102d0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
102e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
102f0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
10300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10310 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
10320 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
10330 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10340 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
10350 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
10360 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
10370 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
10380 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
10390 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
103a0 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
103b0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
103c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
103d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
103e0 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
103f0 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
10400 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
10410 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
10420 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
10430 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
10440 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
10450 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
10460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10470 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
10480 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
10490 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
104a0 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
104b0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
104c0 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
104d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
104e0 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
104f0 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
10500 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
10510 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
10520 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
10530 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10540 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
10550 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
10560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10570 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
10580 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
10590 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
105a0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
105b0 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
105c0 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
105d0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
105e0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
105f0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
10600 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
10610 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
10620 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
10630 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
10640 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
10650 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
10660 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
10670 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
10680 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
10690 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
106a0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
106b0 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
106c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
106d0 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
106e0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
106f0 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
10700 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
10710 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
10720 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
10730 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
10740 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
10750 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
10760 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
10770 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
10780 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
10790 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
107a0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
107b0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
107c0 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
107d0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
107e0 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
107f0 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
10800 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
10810 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
10820 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
10830 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
10840 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
10850 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
10860 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
10870 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
10880 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
10890 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
108a0 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
108b0 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
108c0 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
108d0 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
108e0 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
108f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
10900 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
10910 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
10920 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
10930 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
10940 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
10950 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
10960 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
10970 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
10980 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
10990 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
109a0 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
109b0 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
109c0 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
109d0 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
109e0 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
109f0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
10a00 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c   xMalloc, xReall
10a10 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65  oc, and xFree me
10a20 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
10a30 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
10a40 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
10a50 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
10a60 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
10a70 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
10a80 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ..** ^SQLite gua
10a90 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
10aa0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10ab0 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
10ac0 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
10ad0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
10ae0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
10af0 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53  oundup..**.** xS
10b00 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
10b10 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
10b20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
10b30 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
10b40 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
10b50 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
10b60 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
10b70 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10b80 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
10b90 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
10ba0 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
10bb0 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
10bc0 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
10bd0 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
10be0 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
10bf0 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
10c00 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
10c10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10c20 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
10c30 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
10c40 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
10c50 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
10c60 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
10c70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
10c80 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
10c90 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
10ca0 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
10cb0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
10cc0 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
10cd0 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
10ce0 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
10cf0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10d00 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
10d10 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
10d20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
10d30 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
10d40 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
10d50 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
10d60 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
10d70 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
10d80 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
10d90 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
10da0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
10db0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
10dc0 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
10dd0 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
10de0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46  ry allocator.  F
10df0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
10e00 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
10e10 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
10e20 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
10e30 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
10e40 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
10e50 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
10e60 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
10e70 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
10e80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10e90 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
10ea0 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
10eb0 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
10ec0 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
10ed0 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
10ee0 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
10ef0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
10f00 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
10f10 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
10f20 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
10f30 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
10f40 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
10f50 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
10f60 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
10f70 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
10f80 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
10f90 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
10fa0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
10fb0 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
10fc0 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
10fd0 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
10fe0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
10ff0 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
11000 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
11010 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
11020 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
11030 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
11040 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
11050 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
11060 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
11070 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
11080 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11090 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
110a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
110b0 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
110c0 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
110d0 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
110e0 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
110f0 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
11100 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
11110 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
11120 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
11130 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
11140 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
11150 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
11160 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
11170 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
11180 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
11190 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
111a0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
111b0 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
111c0 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
111d0 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
111e0 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
111f0 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
11200 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
11210 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
11220 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
11230 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11240 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
11250 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
11260 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
11270 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
11280 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
11290 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
112a0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
112b0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
112c0 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
112d0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
112e0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
112f0 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
11300 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
11310 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11320 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
11330 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
11340 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
11350 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
11360 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
11370 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
11380 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
11390 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
113a0 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
113b0 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
113c0 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
113d0 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
113e0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
113f0 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11400 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
11410 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
11420 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
11430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11440 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
11450 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
11460 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
11470 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
11480 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
11490 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
114a0 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
114b0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
114c0 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
114d0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
114e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
114f0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
11500 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
11510 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11520 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
11530 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
11540 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11550 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
11560 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11570 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
11580 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11590 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
115a0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
115b0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
115c0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
115d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
115e0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
115f0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
11600 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
11610 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
11620 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
11630 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
11640 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
11650 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
11660 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
11670 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
11680 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
11690 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
116a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
116b0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
116c0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
116d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
116e0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
116f0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
11700 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11710 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
11720 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11730 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
11740 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11750 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
11760 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11770 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
11780 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
11790 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
117a0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
117b0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
117c0 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
117d0 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
117e0 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
117f0 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
11800 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
11810 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
11820 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
11830 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11840 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11850 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11860 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11870 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11880 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11890 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
118a0 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
118b0 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
118c0 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
118d0 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
118e0 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
118f0 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
11900 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11910 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
11920 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
11930 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
11940 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11950 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
11960 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11970 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11990 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
119a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
119b0 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
119c0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
119d0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
119e0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
119f0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11a00 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11a10 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
11a20 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
11a30 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
11a40 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
11a50 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
11a60 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
11a70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11a80 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
11a90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
11aa0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
11ab0 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
11ac0 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
11ad0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
11ae0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11af0 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
11b00 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
11b10 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
11b20 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
11b30 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
11b40 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
11b50 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
11b60 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
11b70 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
11b80 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
11b90 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
11ba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11bb0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
11bc0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
11bd0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11be0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11bf0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11c00 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11c10 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11c20 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
11c30 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
11c40 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
11c50 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
11c60 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
11c70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11c80 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
11c90 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
11ca0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
11cb0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
11cc0 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
11cd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11ce0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11cf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11d00 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
11d10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11d20 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
11d30 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11d40 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11d50 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11d60 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11d70 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11d80 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
11d90 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
11da0 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
11db0 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
11dc0 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
11dd0 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
11de0 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
11df0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11e00 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11e10 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11e20 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
11e30 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
11e40 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
11e50 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11e60 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
11e70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
11e80 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
11e90 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
11ea0 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
11eb0 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
11ec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
11ed0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11ee0 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
11ef0 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
11f00 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
11f10 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
11f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11f30 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
11f40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11f50 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
11f60 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
11f70 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
11f80 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11f90 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11fa0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11fb0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11fc0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11fd0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11fe0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
11ff0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12000 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
12010 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
12020 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
12030 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
12040 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12050 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12060 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12080 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
12090 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
120a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
120b0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
120c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
120d0 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
120e0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
120f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12100 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12110 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12120 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20   which is .** a 
12130 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12140 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12150 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12160 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12170 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
12180 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12190 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
121a0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
121b0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
121c0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
121d0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
121e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
121f0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12200 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
12210 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
12220 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
12230 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
12240 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12250 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12260 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
12270 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12280 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
12290 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
122a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
122b0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
122c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
122d0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
122e0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
122f0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12300 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
12310 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
12320 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
12330 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12340 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12350 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12360 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12370 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
12380 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
12390 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
123a0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
123b0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
123c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
123d0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
123e0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
123f0 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
12400 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
12410 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12420 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12430 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
12440 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
12450 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12460 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
12470 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
12480 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
12490 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
124a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
124b0 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
124c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
124d0 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
124e0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
124f0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70  FIG_MEMSTATUS op
12500 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
12510 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
12520 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72  pe int,.** inter
12530 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
12540 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
12550 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
12560 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
12570 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12580 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12590 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
125a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
125b0 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73  stics are.** dis
125c0 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f  abled, the follo
125d0 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
125e0 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
125f0 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
12600 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
12610 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
12620 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
12630 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
12640 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
12650 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12660 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
12670 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
12680 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
12690 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
126a0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
126b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
126c0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
126d0 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
126e0 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
126f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
12700 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
12710 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
12720 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
12730 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
12740 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12750 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12760 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
12770 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12780 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
12790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
127a0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
127b0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
127c0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
127d0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
127e0 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
127f0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ffer.** that SQL
12800 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
12810 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
12820 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72   ^(There are thr
12830 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  ee arguments.** 
12840 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
12850 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69  _SCRATCH:  A poi
12860 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
12870 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
12880 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
12890 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
128a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
128b0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
128c0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
128d0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
128e0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
128f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
12900 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
12910 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a  cations (N).)^.*
12920 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12930 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12940 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
12950 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
12960 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
12970 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12980 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
12990 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20  te will not use 
129a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
129b0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
129c0 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51  r thread..** ^SQ
129d0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
129e0 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63  request a scratc
129f0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
12a00 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
12a10 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
12a20 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
12a30 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
12a40 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
12a50 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
12a60 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
12a70 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12a80 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
12a90 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
12aa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
12ab0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
12ac0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
12ad0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
12ae0 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  <p>.** ^When the
12af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f   application pro
12b00 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74  vides any amount
12b10 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f   of scratch memo
12b20 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ry using.** SQLI
12b30 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12b40 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73  H, SQLite avoids
12b50 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72   unnecessary lar
12b60 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  ge.** [sqlite3_m
12b70 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63  alloc|heap alloc
12b80 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73  ations]..** This
12b90 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f   can help [Robso
12ba0 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20  n proof|prevent 
12bb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12bc0 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20  n failures] due 
12bd0 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d  to heap.** fragm
12be0 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d  entation in low-
12bf0 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20  memory embedded 
12c00 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64  systems..** </dd
12c10 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12c20 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12c30 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
12c40 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
12c50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12c70 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
12c80 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12c90 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12ca0 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
12cb0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
12cc0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
12cd0 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
12ce0 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
12cf0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12d00 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
12d10 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
12d20 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
12d30 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
12d40 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
12d50 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12d60 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
12d70 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
12d80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
12d90 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
12da0 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68  n option..** ^Th
12db0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12dc0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
12dd0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
12de0 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
12df0 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
12e00 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
12e10 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
12e20 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
12e30 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
12e40 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
12e50 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
12e60 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
12e70 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
12e80 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
12e90 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
12ea0 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
12eb0 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
12ec0 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
12ed0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
12ee0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
12ef0 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
12f00 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
12f10 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
12f20 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
12f30 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
12f40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12f50 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69  ACHE_HDRSZ] opti
12f60 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  on .** to [sqlit
12f70 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
12f80 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
12f90 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
12fa0 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
12fb0 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
12fc0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
12fd0 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
12fe0 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ary.  The first.
12ff0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
13000 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ld pointer to an
13010 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13020 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
13030 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65  that.** is at le
13040 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
13050 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77  f memory, otherw
13060 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62  ise subsequent b
13070 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
13080 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c  defined..** ^SQL
13090 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
130a0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
130b0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
130c0 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
130d0 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
130e0 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
130f0 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
13100 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
13110 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
13120 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13130 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13140 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13150 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13160 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
13170 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
13180 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13190 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
131a0 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
131b0 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
131c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
131d0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
131e0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
131f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13200 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13210 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
13220 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13230 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
13240 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13250 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
13260 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
13270 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13280 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
13290 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
132a0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
132b0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
132c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
132d0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
132e0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
132f0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
13300 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
13310 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
13320 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
13330 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
13340 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
13350 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13360 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
13370 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
13380 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
13390 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
133a0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
133b0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
133c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
133d0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
133e0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
133f0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
13400 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13410 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
13420 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
13430 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13440 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
13450 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
13460 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
13470 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
13480 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
13490 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
134a0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
134b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
134c0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
134d0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
134e0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
134f0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
13500 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
13510 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13520 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
13530 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
13540 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
13550 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
13560 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
13570 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
13580 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
13590 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
135a0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
135b0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
135c0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
135d0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
135e0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
135f0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
13600 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
13610 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
13620 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
13630 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
13640 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13650 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
13660 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
13670 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
13680 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
13690 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
136a0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
136b0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
136c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
136d0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
136e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
136f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13700 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13710 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
13720 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13730 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
13740 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
13750 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13760 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13770 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13780 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
13790 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
137a0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
137b0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
137c0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
137d0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
137e0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
137f0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
13800 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13810 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
13820 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
13830 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13840 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13850 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
13860 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
13870 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
13880 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
13890 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
138a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
138b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
138c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
138d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
138e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
138f0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
13900 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
13910 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
13920 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
13930 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
13940 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13950 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13960 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
13970 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13980 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13990 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
139a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
139b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
139c0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
139d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
139e0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
139f0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13a00 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
13a10 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13a20 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13a30 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
13a40 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13a50 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13a60 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13a70 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
13a80 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
13a90 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
13aa0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
13ab0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
13ac0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
13ad0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
13ae0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13af0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13b00 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13b10 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
13b20 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
13b30 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
13b40 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
13b50 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
13b60 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
13b70 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
13b80 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
13b90 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13ba0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13bb0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13bc0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13bd0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13be0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13bf0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
13c00 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
13c10 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
13c20 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
13c30 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
13c40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
13c50 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
13c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13c70 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
13c80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13c90 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13ca0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13cb0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13cc0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13cd0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13ce0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13cf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13d00 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13d10 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
13d20 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
13d30 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
13d40 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
13d50 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
13d60 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
13d70 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
13d80 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
13d90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13da0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
13db0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
13dc0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
13dd0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
13de0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
13df0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
13e00 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
13e10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
13e20 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
13e30 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
13e40 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
13e50 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
13e60 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
13e70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13e80 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
13e90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
13ea0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
13eb0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
13ec0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
13ed0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13ee0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
13ef0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
13f00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13f10 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
13f20 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13f30 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
13f40 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13f50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13f60 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
13f70 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13f80 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
13f90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13fa0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
13fb0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
13fc0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
13fd0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
13fe0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
13ff0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
14000 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14010 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
14020 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
14030 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
14040 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14050 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
14060 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14070 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
14080 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14090 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
140a0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
140b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
140c0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
140d0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
140e0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
140f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14100 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14110 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14120 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
14130 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
14140 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
14150 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
14160 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
14170 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14180 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14190 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
141a0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
141b0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
141c0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
141d0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
141e0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
141f0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
14200 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
14210 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14220 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
14230 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14240 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
14250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
14260 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
14270 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
14280 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
14290 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
142a0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
142b0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
142c0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
142d0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
142e0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
142f0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
14300 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
14310 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
14320 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
14330 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
14340 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
14350 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
14360 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
14370 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
14380 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
14390 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
143a0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
143b0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
143c0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
143d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
143e0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
143f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
14400 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
14410 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
14420 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
14430 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
14440 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
14450 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
14460 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
14470 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
14480 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
14490 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
144a0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
144b0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
144c0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
144d0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
144e0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
144f0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
14500 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
14510 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
14520 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
14530 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
14540 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
14550 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
14560 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
14570 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
14580 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
14590 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
145a0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
145b0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
145c0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
145d0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
145e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
145f0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
14600 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
14610 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
14620 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
14630 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
14640 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
14650 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14660 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
14670 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14680 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
14690 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
146a0 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
146b0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
146c0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
146d0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
146e0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
146f0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
14700 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
14710 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
14720 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
14730 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
14740 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
14750 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
14760 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
14770 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
14780 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
14790 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
147a0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
147b0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
147c0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
147d0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
147e0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
147f0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
14800 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
14810 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
14820 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
14830 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
14840 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
14850 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
14860 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
14870 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
14880 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
14890 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
148a0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
148b0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
148c0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
148d0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
148e0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
148f0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
14900 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
14910 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
14920 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
14930 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
14940 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
14950 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
14960 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
14970 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
14980 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
14990 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
149a0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
149b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
149c0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
149d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
149e0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
149f0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
14a00 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14a10 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14a20 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
14a30 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
14a40 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
14a50 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
14a60 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14a70 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
14a80 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
14a90 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
14aa0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14ab0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14ac0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
14ad0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
14ae0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
14af0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
14b00 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
14b10 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
14b20 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
14b30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14b40 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
14b50 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
14b60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
14b70 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
14b80 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
14b90 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
14ba0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
14bb0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
14bc0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
14bd0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
14be0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
14bf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
14c00 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
14c10 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
14c20 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
14c30 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
14c40 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
14c50 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
14c60 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
14c70 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
14c80 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
14c90 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
14ca0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
14cb0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
14cc0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
14cd0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
14ce0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
14cf0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14d00 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
14d10 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14d20 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
14d30 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14d40 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
14d50 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
14d60 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
14d70 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
14d80 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
14d90 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
14da0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
14db0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
14dc0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
14dd0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14de0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14df0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
14e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
14e10 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
14e20 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
14e30 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
14e40 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14e50 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
14e60 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
14e70 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
14e80 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
14e90 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
14ea0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
14eb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
14ec0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
14ed0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
14ee0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
14ef0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
14f00 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
14f10 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
14f20 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
14f30 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
14f40 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
14f50 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
14f60 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
14f70 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
14f80 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
14f90 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14fa0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
14fb0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14fc0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
14fd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14fe0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
14ff0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15000 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
15010 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
15020 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
15030 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15040 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15050 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15060 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
15070 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
15080 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15090 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
150a0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
150b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
150c0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
150d0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
150e0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
150f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15100 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
15110 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
15120 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
15130 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15140 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
15150 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
15160 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
15170 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
15180 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
15190 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
151a0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
151b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
151c0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
151d0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
151e0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
151f0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
15200 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
15210 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
15220 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15230 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
15240 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15250 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
15260 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
15270 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
15280 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
15290 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
152a0 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
152b0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
152c0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
152d0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
152e0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
152f0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
15300 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
15310 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15320 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
15330 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15340 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
15350 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
15360 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15370 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
15380 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
15390 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
153a0 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
153b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
153c0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
153d0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
153e0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
153f0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
15400 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
15410 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
15420 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
15430 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
15440 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
15450 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
15460 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
15470 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
15480 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
15490 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
154a0 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
154b0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
154c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
154d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
154e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
154f0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
15500 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
15510 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
15520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15530 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
15540 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15550 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15560 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15570 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15580 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
15590 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
155a0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
155b0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
155c0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
155d0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
155e0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
155f0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
15600 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
15610 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15620 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
15630 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
15640 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
15650 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
15660 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
15670 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
15680 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  p..** </dl>.**.*
15690 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
156a0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d  G_PCACHE_HDRSZ]]
156b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
156c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
156d0 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
156e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
156f0 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e  CHE_HDRSZ option
15700 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15710 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
15720 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
15730 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
15740 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68  d writes into th
15750 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e  at integer the n
15760 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a  umber of extra.*
15770 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65  * bytes per page
15780 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61   required for ea
15790 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49  ch page in [SQLI
157a0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
157b0 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f  CHE]..** The amo
157c0 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61  unt of extra spa
157d0 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20  ce required can 
157e0 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67  change depending
157f0 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72   on the compiler
15800 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74  ,.** target plat
15810 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65  form, and SQLite
15820 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20   version..**.** 
15830 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15840 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  PMASZ]].** <dt>S
15850 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
15860 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  SZ.** <dd>^The S
15870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
15880 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
15890 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
158a0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
158b0 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  n unsigned integ
158c0 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20  er and sets the 
158d0 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a  "Minimum PMA Siz
158e0 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69  e" for the multi
158f0 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74  threaded.** sort
15900 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67  er to that integ
15910 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  er.  The default
15920 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a   minimum PMA Siz
15930 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a  e is set by the.
15940 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45  ** [SQLITE_SORTE
15950 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65  R_PMASZ] compile
15960 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e  -time option.  N
15970 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c  ew threads are l
15980 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65  aunched.** to he
15990 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65  lp with sort ope
159a0 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c  rations when mul
159b0 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69  tithreaded sorti
159c0 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64  ng.** is enabled
159d0 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41   (using the [PRA
159e0 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d  GMA threads] com
159f0 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d  mand) and the am
15a00 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a  ount of content.
15a10 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20  ** to be sorted 
15a20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65  exceeds the page
15a30 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20   size times the 
15a40 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a  minimum of the.*
15a50 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f  * [PRAGMA cache_
15a60 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e  size] setting an
15a70 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a  d this value..**
15a80 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
15a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15aa0 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
15ab0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15ac0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15ad0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
15ae0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
15af0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15b00 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
15b10 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
15b20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15b30 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
15b40 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
15b50 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15b60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15b70 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
15b80 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
15b90 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
15ba0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15bb0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
15bc0 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
15bd0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
15be0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15bf0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
15c00 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
15c10 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
15c20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
15c30 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
15c40 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
15c50 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
15c60 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
15c70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15c80 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
15c90 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
15ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15cb0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
15cc0 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
15cd0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15ce0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15cf0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
15d00 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
15d10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
15d20 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
15d30 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
15d40 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
15d50 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
15d60 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
15d70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15d80 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
15d90 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
15da0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15db0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
15dc0 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
15dd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15de0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15df0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
15e00 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
15e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15e20 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
15e30 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
15e40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15e50 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
15e60 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
15e70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15e80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
15e90 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
15ea0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15eb0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
15ec0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15ed0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
15ee0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
15ef0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
15f00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15f10 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15f20 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
15f30 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15f40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15f50 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
15f60 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
15f70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15f80 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15f90 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
15fa0 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
15fb0 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
15fc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15fd0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15fe0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
15ff0 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
16000 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16010 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
16020 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
16030 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
16040 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
16050 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
16060 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
16070 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f   int szPma */../
16080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
16090 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
160a0 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
160b0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
160c0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
160d0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
160e0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
160f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
16100 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
16110 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
16120 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
16130 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
16140 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
16150 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
16160 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16170 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
16180 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
16190 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
161a0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
161b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
161c0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
161d0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
161e0 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
161f0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
16200 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
16210 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
16220 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
16230 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
16240 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
16250 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16260 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
16270 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
16280 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
16290 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
162a0 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
162b0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
162c0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
162d0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
162e0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
162f0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
16300 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
16310 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
16320 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
16330 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
16340 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
16350 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
16360 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
16370 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
16380 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
16390 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
163a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
163b0 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
163c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
163d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
163e0 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
163f0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
16400 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
16410 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
16420 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
16430 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
16440 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
16450 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16460 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
16470 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
16480 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
16490 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
164a0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
164b0 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
164c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
164d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
164e0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
164f0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
16500 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
16510 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
16520 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
16530 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
16540 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
16550 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
16560 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16570 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
16580 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
16590 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
165a0 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
165b0 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
165c0 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
165d0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
165e0 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
165f0 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
16600 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
16610 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
16620 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16630 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
16640 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
16650 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
16660 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
16670 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
16680 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
16690 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
166a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
166b0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
166c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
166d0 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
166e0 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
166f0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
16700 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
16710 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
16720 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
16730 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
16740 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
16750 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
16760 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
16770 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
16780 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
16790 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
167a0 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
167b0 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
167c0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
167d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
167e0 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
167f0 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
16800 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
16810 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
16820 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
16830 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
16840 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
16850 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
16860 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
16870 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
16880 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
16890 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
168a0 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
168b0 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
168c0 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
168d0 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
168e0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
168f0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
16900 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
16910 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
16920 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
16930 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
16940 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
16950 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
16960 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
16970 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
16980 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
16990 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
169a0 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
169b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
169c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
169d0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
169e0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
169f0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
16a00 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
16a10 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
16a20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
16a30 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
16a40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16a50 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
16a60 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
16a70 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
16a80 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
16a90 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
16aa0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
16ab0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
16ac0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16ad0 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
16ae0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16af0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
16b00 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
16b10 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
16b20 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
16b30 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
16b40 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
16b50 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
16b60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16b70 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
16b80 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
16b90 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
16ba0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
16bb0 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
16bc0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16bd0 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
16be0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
16bf0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16c00 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
16c10 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
16c20 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
16c30 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
16c40 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
16c50 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
16c60 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
16c70 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
16c80 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
16c90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16ca0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
16cb0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
16cc0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
16cd0 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
16ce0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
16cf0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
16d00 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16d10 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16d20 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
16d30 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
16d40 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
16d50 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
16d60 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
16d70 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
16d80 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
16d90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16da0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
16db0 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
16dc0 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
16dd0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
16de0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
16df0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
16e00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
16e10 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
16e20 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
16e30 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
16e40 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
16e50 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
16e60 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
16e70 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
16e80 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
16e90 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
16ea0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
16eb0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
16ec0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69  patibility..*/.i
16ed0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
16ee0 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
16ef0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
16f00 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
16f10 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
16f20 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
16f30 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
16f40 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
16f50 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
16f60 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
16f70 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
16f80 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
16f90 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
16fa0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
16fb0 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
16fc0 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
16fd0 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
16fe0 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
16ff0 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
17000 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
17010 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
17020 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
17030 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
17040 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
17050 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
17060 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
17070 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
17080 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
17090 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
170a0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
170b0 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
170c0 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
170d0 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
170e0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
170f0 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
17100 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
17110 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
17120 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74   .** most recent
17130 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
17140 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
17150 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
17160 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
17170 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17180 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65  tion D..** ^Inse
17190 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
171a0 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
171b0 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64  are not recorded
171c0 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
171d0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
171e0 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
171f0 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  es.** have ever 
17200 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20  occurred on the 
17210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17220 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20  ion D, .** then 
17230 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17240 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
17250 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
17260 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
17270 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
17280 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
17290 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
172a0 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
172b0 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
172c0 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
172d0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
172e0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
172f0 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
17300 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
17310 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
17320 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
17330 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
17340 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
17350 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
17360 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
17370 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
17380 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
17390 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
173a0 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
173b0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
173c0 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
173d0 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
173e0 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
173f0 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
17400 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
17410 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
17420 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17430 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
17440 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
17450 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
17460 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
17470 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
17480 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
17490 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
174a0 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
174b0 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
174c0 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
174d0 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
174e0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
174f0 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
17500 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
17510 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
17520 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
17530 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
17540 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
17550 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
17560 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
17570 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
17580 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
17590 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
175a0 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
175b0 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
175c0 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
175d0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
175e0 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
175f0 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
17600 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
17610 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
17620 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
17630 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
17640 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
17650 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
17660 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
17670 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
17680 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
17690 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
176a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
176b0 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
176c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
176d0 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
176e0 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
176f0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
17700 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17710 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
17720 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
17730 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
17740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17750 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
17760 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17770 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
17780 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
17790 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
177a0 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
177b0 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
177c0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
177d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
177e0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
177f0 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
17800 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
17810 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
17820 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
17830 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
17840 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
17850 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
17860 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
17870 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
17880 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17890 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
178a0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
178b0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
178c0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
178d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
178e0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
178f0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
17900 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
17910 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
17920 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
17930 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
17940 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
17950 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
17960 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
17970 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
17980 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
17990 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
179a0 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
179b0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
179c0 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
179d0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
179e0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
179f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
17a00 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
17a10 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
17a20 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
17a30 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
17a40 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
17a50 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
17a60 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
17a70 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17a80 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
17a90 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
17aa0 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
17ab0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
17ac0 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
17ad0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
17ae0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
17af0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
17b00 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
17b10 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
17b20 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
17b30 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
17b40 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
17b50 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
17b60 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
17b70 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
17b80 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
17b90 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
17ba0 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
17bb0 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
17bc0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
17bd0 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
17be0 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
17bf0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
17c00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
17c10 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
17c20 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
17c30 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
17c40 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
17c50 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
17c60 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
17c70 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
17c80 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
17c90 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
17ca0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
17cb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
17cc0 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
17cd0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
17ce0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
17cf0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
17d00 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
17d10 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
17d20 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
17d30 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
17d40 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
17d50 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17d60 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
17d70 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17d80 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
17d90 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
17da0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
17db0 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
17dc0 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
17dd0 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
17de0 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
17df0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
17e00 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
17e10 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
17e20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
17e30 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
17e40 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
17e50 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
17e60 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
17e70 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
17e80 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
17e90 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
17ea0 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
17eb0 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
17ec0 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
17ed0 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
17ee0 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
17ef0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
17f00 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
17f10 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
17f20 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
17f30 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
17f40 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
17f50 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
17f60 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
17f70 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
17f80 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
17f90 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
17fa0 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
17fb0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
17fc0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
17fd0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
17fe0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
17ff0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
18000 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
18010 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
18020 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
18030 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
18040 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
18050 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
18060 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
18070 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
18080 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
18090 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
180a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
180b0 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
180c0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
180d0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
180e0 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
180f0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
18100 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18110 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
18120 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
18130 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
18140 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
18150 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
18160 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
18170 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
18180 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
18190 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
181a0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
181b0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
181c0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
181d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
181e0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
181f0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
18200 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18210 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18220 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
18230 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
18240 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
18250 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
18260 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
18270 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
18280 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
18290 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
182a0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
182b0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
182c0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
182d0 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
182e0 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
182f0 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
18300 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
18310 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
18320 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
18330 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
18340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18350 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
18360 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
18370 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
18380 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
18390 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
183a0 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
183b0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
183c0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
183d0 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
183e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
183f0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18400 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
18410 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
18420 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
18430 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
18440 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
18450 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
18460 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
18470 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
18480 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
18490 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
184a0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
184b0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
184c0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
184d0 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
184e0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
184f0 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
18500 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
18510 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
18520 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
18530 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
18540 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
18550 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18560 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18570 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18580 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
18590 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
185a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
185b0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
185c0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
185d0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
185e0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
185f0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
18600 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18610 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18620 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
18630 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
18640 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
18650 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
18660 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
18670 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
18680 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
18690 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
186a0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
186b0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
186c0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
186d0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
186e0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
186f0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
18700 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
18710 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
18720 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
18730 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
18740 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
18750 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
18760 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
18770 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
18780 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
18790 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
187a0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
187b0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
187c0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
187d0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
187e0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
187f0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
18800 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
18810 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
18820 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
18830 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
18840 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
18850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
18860 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
18870 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
18880 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
18890 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
188a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
188b0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
188c0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
188d0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
188e0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
188f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
18900 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
18910 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
18920 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
18930 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
18940 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
18950 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
18960 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
18970 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
18980 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
18990 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
189a0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
189b0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
189c0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
189d0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
189e0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
189f0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
18a00 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
18a10 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
18a20 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
18a30 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
18a40 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
18a50 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
18a60 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
18a70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18a80 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
18a90 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
18aa0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
18ab0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
18ac0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
18ad0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
18ae0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
18af0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
18b00 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
18b10 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
18b20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18b30 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
18b40 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
18b50 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
18b60 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
18b70 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
18b80 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
18b90 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
18ba0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
18bb0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18bc0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
18bd0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
18be0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
18bf0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
18c00 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
18c10 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
18c20 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
18c30 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
18c40 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
18c50 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
18c60 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
18c70 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
18c80 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
18c90 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18ca0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
18cb0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
18cc0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
18cd0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
18ce0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
18cf0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18d00 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
18d10 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
18d20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
18d30 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
18d40 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
18d50 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
18d60 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
18d70 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
18d80 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
18d90 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
18da0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
18db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18dc0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
18dd0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
18de0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
18df0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
18e00 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
18e10 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
18e20 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
18e30 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
18e40 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
18e50 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
18e60 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
18e70 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
18e80 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
18e90 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
18ea0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
18eb0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
18ec0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
18ed0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
18ee0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
18ef0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
18f00 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
18f10 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
18f20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
18f30 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
18f40 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
18f50 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
18f60 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
18f70 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
18f80 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
18f90 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
18fa0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
18fb0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
18fc0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
18fd0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
18fe0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
18ff0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
19000 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
19010 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
19020 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
19030 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
19040 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
19050 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
19060 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
19070 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
19080 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
19090 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
190a0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
190b0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
190c0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
190d0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
190e0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
190f0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
19100 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
19110 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
19120 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
19130 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
19140 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
19150 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
19160 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
19170 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
19180 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
19190 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
191a0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
191b0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
191c0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
191d0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
191e0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
191f0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
19200 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
19210 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
19220 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
19230 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
19240 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
19250 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
19260 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
19270 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
19280 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
19290 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
192a0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
192b0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
192c0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
192d0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
192e0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
192f0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
19300 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
19310 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
19320 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
19330 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
19340 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19350 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
19360 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
19370 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
19380 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
19390 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
193a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
193b0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
193c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
193d0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
193e0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
193f0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
19400 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19410 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
19420 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
19430 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
19440 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
19450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
19460 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
19470 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
19480 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
19490 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
194a0 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
194b0 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
194c0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
194d0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
194e0 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
194f0 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
19500 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
19510 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
19520 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
19530 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
19540 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
19550 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
19560 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
19570 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
19580 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
19590 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
195a0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
195b0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
195c0 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
195d0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
195e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
195f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
19600 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
19610 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
19620 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
19630 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
19640 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
19650 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
19660 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
19670 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
19680 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
19690 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
196a0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
196b0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
196c0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
196d0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
196e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
196f0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
19700 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
19710 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
19720 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
19730 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19740 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
19750 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
19760 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
19770 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
19780 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
19790 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
197a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
197b0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
197c0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
197d0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
197e0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
197f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
19800 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
19810 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20   previously for 
19820 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
19830 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
19840 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
19850 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
19860 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
19870 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
19880 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
19890 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
198a0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
198b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
198c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
198d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
198e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
198f0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
19900 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
19910 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
19920 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
19930 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
19940 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
19950 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
19960 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
19970 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
19980 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
19990 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
199a0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
199b0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
199c0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
199d0 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
199e0 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
199f0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
19a00 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
19a10 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
19a20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
19a30 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
19a40 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
19a50 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
19a60 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
19a70 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
19a80 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
19a90 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
19aa0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
19ab0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
19ac0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
19ad0 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
19ae0 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
19af0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19b00 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
19b10 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
19b20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
19b30 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
19b40 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
19b50 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
19b60 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
19b70 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
19b80 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
19b90 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
19ba0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
19bb0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
19bc0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
19bd0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19be0 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
19bf0 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
19c00 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
19c10 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
19c20 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
19c30 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
19c40 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
19c50 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
19c60 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
19c70 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
19c80 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
19c90 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
19ca0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
19cb0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
19cc0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
19cd0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
19ce0 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
19cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
19d00 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
19d10 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
19d20 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
19d30 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
19d40 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
19d50 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
19d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19d70 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
19d80 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
19d90 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
19da0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
19db0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
19dc0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
19dd0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
19de0 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
19df0 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
19e00 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
19e10 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
19e20 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
19e30 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
19e40 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
19e50 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
19e60 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
19e70 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
19e80 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
19e90 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
19ea0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
19eb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
19ec0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
19ed0 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
19ee0 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
19ef0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19f00 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
19f10 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
19f20 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19f30 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
19f40 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
19f50 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
19f60 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
19f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19f80 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
19f90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19fa0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19fb0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
19fc0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19fd0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
19fe0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
19ff0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
1a000 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1a010 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1a020 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1a030 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1a040 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a050 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1a060 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1a070 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1a080 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1a090 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1a0a0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1a0b0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1a0c0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1a0d0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1a0e0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1a0f0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1a100 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1a110 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1a120 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1a130 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1a140 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1a150 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1a160 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1a170 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1a180 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1a190 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1a1a0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1a1b0 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1a1c0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1a1d0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1a1e0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1a1f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1a200 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1a210 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1a220 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1a230 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1a240 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1a250 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1a260 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1a270 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1a280 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1a290 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1a2a0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a2b0 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1a2c0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1a2d0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1a2e0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1a2f0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1a300 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1a310 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1a320 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
1a330 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1a340 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1a350 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1a360 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1a370 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1a380 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1a390 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
1a3a0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
1a3b0 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
1a3c0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
1a3d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1a3e0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
1a3f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
1a400 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
1a410 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
1a420 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
1a430 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
1a440 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
1a450 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
1a460 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1a470 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
1a480 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
1a490 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
1a4a0 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
1a4b0 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
1a4c0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
1a4d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
1a4e0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
1a4f0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
1a500 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
1a510 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
1a520 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
1a530 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
1a540 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
1a550 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
1a560 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
1a570 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
1a580 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
1a590 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
1a5a0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1a5b0 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
1a5c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a5d0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
1a5e0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
1a5f0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1a600 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
1a610 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
1a620 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
1a630 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
1a640 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
1a650 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
1a660 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1a670 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
1a680 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
1a690 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
1a6a0 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
1a6b0 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
1a6c0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
1a6d0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
1a6e0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
1a6f0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
1a700 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
1a710 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
1a720 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1a730 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
1a740 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
1a750 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1a760 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1a770 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a780 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1a790 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1a7a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1a7b0 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1a7c0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1a7d0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1a7e0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1a7f0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1a800 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1a810 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1a820 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a830 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1a840 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1a850 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1a860 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1a870 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1a880 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1a890 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1a8a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a8b0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1a8c0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1a8d0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1a8e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1a8f0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1a900 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1a910 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1a920 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1a930 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1a940 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1a950 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1a960 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1a970 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1a980 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1a990 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1a9a0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1a9b0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1a9c0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1a9d0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1a9e0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1a9f0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1aa00 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1aa10 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1aa20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1aa30 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1aa40 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1aa50 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1aa60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1aa70 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1aa80 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1aa90 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1aaa0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1aab0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1aac0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1aad0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1aae0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1aaf0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ab00 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1ab10 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1ab20 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1ab30 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ab40 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1ab50 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ab60 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1ab70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1ab80 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1ab90 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1aba0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1abb0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1abc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1abd0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1abe0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1abf0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1ac00 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1ac10 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1ac20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1ac30 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1ac40 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1ac50 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1ac60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1ac70 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1ac80 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1ac90 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1aca0 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1acb0 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1acc0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1acd0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1ace0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1acf0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1ad00 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1ad10 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1ad20 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1ad30 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ad40 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1ad50 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1ad60 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1ad70 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1ad80 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1ad90 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1ada0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1adb0 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1adc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1add0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1ade0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1adf0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1ae00 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1ae10 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1ae20 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1ae30 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1ae40 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1ae50 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1ae60 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1ae70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ae80 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1ae90 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1aea0 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1aeb0 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1aec0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1aed0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1aee0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1aef0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1af00 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1af10 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1af20 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1af30 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1af40 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1af50 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1af60 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1af70 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1af80 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1af90 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1afa0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1afb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1afc0 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1afd0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1afe0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1aff0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1b000 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1b010 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1b020 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1b030 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1b040 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1b050 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1b060 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1b070 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1b080 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1b090 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1b0a0 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1b0b0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1b0c0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1b0d0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1b0e0 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1b0f0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1b100 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1b110 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1b120 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1b130 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1b140 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1b150 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1b160 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1b170 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1b180 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1b190 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b1a0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1b1b0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1b1c0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1b1d0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1b1e0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1b1f0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1b200 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1b210 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1b220 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1b230 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1b240 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1b250 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1b260 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1b270 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1b280 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1b290 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1b2a0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1b2b0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1b2c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1b2d0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1b2e0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1b2f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1b300 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b310 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1b320 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1b330 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1b340 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1b350 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1b360 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1b370 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1b380 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1b390 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1b3a0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1b3b0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1b3c0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1b3d0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1b3e0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1b3f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1b400 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1b410 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1b420 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1b430 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1b440 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1b450 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1b460 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1b470 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1b480 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1b490 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1b4a0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1b4b0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1b4c0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1b4d0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1b4e0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1b4f0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1b500 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b510 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1b520 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1b530 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1b540 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1b550 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1b560 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1b570 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1b580 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1b590 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1b5a0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1b5b0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1b5c0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1b5d0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1b5e0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1b5f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1b600 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1b610 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1b620 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1b630 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1b640 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1b650 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1b660 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1b670 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1b680 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1b690 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1b6a0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1b6b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b6c0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1b6d0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1b6e0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1b6f0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1b700 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1b710 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1b720 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1b730 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1b740 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1b750 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1b760 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1b770 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1b780 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b790 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1b7a0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1b7b0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1b7c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1b7d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b7e0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1b7f0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1b800 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1b810 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1b820 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1b830 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1b840 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1b850 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1b860 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1b870 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1b880 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1b890 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1b8a0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1b8b0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1b8c0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1b8d0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1b8e0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1b8f0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1b900 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1b910 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1b920 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1b930 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1b940 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1b950 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1b960 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1b970 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1b980 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1b990 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1b9a0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1b9b0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1b9c0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1b9d0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1b9e0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1b9f0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1ba00 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1ba10 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1ba20 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1ba30 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1ba40 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1ba50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ba60 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1ba70 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1ba80 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1ba90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1baa0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1bab0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1bac0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1bad0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1bae0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1baf0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1bb00 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1bb10 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1bb20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1bb30 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1bb40 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1bb50 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1bb60 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1bb70 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1bb80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1bb90 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1bba0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1bbb0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1bbc0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1bbd0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1bbe0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1bbf0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1bc00 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1bc10 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1bc20 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1bc30 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1bc40 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1bc50 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1bc60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1bc70 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1bc80 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1bc90 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1bca0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1bcb0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1bcc0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1bcd0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1bce0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1bcf0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1bd00 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1bd10 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1bd20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1bd30 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1bd40 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1bd50 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1bd60 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1bd70 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1bd80 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1bd90 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1bda0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1bdb0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1bdc0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1bdd0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1bde0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1bdf0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1be00 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1be10 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1be20 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1be30 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1be40 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1be50 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1be60 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1be70 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1be80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1be90 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1bea0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1beb0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1bec0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1bed0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1bee0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1bef0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1bf00 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1bf10 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1bf20 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1bf30 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1bf40 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1bf50 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1bf60 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1bf70 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1bf80 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1bf90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1bfa0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1bfb0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1bfc0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1bfd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1bfe0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1bff0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1c000 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1c010 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1c020 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1c030 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1c040 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1c050 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1c060 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1c070 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1c080 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1c090 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1c0a0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1c0b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c0c0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1c0d0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1c0e0 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1c0f0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1c100 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1c110 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1c120 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1c130 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1c140 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1c150 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1c160 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1c170 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1c180 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1c190 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1c1a0 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1c1b0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1c1c0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1c1d0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1c1e0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1c1f0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1c200 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1c210 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1c220 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1c230 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1c240 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1c250 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1c260 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1c270 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1c280 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1c290 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1c2a0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1c2b0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1c2c0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1c2d0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1c2e0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1c2f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1c300 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1c310 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1c320 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1c330 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1c340 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1c350 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1c360 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1c370 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1c380 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1c390 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1c3a0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1c3b0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1c3c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1c3d0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1c3e0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1c3f0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1c400 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1c410 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1c420 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1c430 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1c440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c450 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1c460 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1c470 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1c480 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1c490 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1c4a0 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1c4b0 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1c4c0 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1c4d0 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1c4e0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1c4f0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1c500 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1c510 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1c520 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1c530 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1c540 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1c550 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1c560 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1c570 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1c580 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1c590 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1c5a0 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1c5b0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1c5c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1c5d0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1c5e0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1c5f0 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1c600 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1c610 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1c620 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1c630 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1c640 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1c650 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1c660 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1c670 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1c680 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1c690 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1c6a0 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1c6b0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1c6c0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1c6d0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1c6e0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1c6f0 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1c700 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1c710 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1c720 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1c730 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1c740 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1c750 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1c760 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1c770 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1c780 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1c790 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1c7a0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1c7b0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1c7c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c7d0 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1c7e0 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1c7f0 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1c800 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1c810 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1c820 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1c830 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1c840 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1c850 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1c860 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1c870 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1c880 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1c890 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1c8a0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1c8b0 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1c8c0 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1c8d0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1c8e0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1c8f0 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1c900 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c910 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1c920 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1c930 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1c940 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1c950 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1c960 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1c970 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1c980 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1c990 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1c9a0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1c9b0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1c9c0 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1c9d0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1c9e0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1c9f0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1ca00 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1ca10 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1ca20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ca30 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1ca40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1ca50 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1ca60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1ca70 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1ca80 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1ca90 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1caa0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1cab0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1cac0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1cad0 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
1cae0 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
1caf0 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
1cb00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1cb10 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
1cb20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
1cb30 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
1cb40 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
1cb50 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
1cb60 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
1cb70 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
1cb80 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
1cb90 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
1cba0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1cbb0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1cbc0 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
1cbd0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
1cbe0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1cbf0 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
1cc00 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1cc10 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
1cc20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
1cc30 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
1cc40 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
1cc50 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1cc60 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
1cc70 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
1cc80 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
1cc90 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
1cca0 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
1ccb0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
1ccc0 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1ccd0 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1cce0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1ccf0 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
1cd00 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
1cd10 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
1cd20 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
1cd30 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
1cd40 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
1cd50 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
1cd60 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
1cd70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1cd80 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
1cd90 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
1cda0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
1cdb0 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
1cdc0 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
1cdd0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
1cde0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
1cdf0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1ce00 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1ce10 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
1ce20 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1ce30 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1ce40 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1ce50 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
1ce60 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1ce70 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1ce80 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1ce90 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1cea0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1ceb0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1cec0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1ced0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1cee0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1cef0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1cf00 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1cf10 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1cf20 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1cf30 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1cf40 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1cf50 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1cf60 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1cf70 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1cf80 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1cf90 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1cfa0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1cfb0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1cfc0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1cfd0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1cfe0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1cff0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1d000 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1d010 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1d020 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1d030 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1d040 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1d050 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1d060 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1d070 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1d080 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1d090 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1d0a0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1d0b0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1d0c0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1d0d0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1d0e0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1d0f0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1d100 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1d110 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1d120 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1d130 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1d140 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1d150 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1d160 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1d170 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1d180 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1d190 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1d1a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1d1b0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1d1c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d1d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1d1e0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1d1f0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1d200 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1d210 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1d220 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1d230 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1d240 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1d250 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d260 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1d270 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1d280 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1d290 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1d2a0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1d2b0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1d2c0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1d2d0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1d2e0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1d2f0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1d300 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1d310 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1d320 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1d330 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1d340 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1d350 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
1d360 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
1d370 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1d380 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1d390 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1d3a0 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1d3b0 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1d3c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1d3d0 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
1d3e0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
1d3f0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1d400 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1d410 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1d420 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1d430 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1d440 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1d450 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1d460 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1d470 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1d480 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1d490 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1d4a0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1d4b0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1d4c0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1d4d0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1d4e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1d4f0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1d500 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1d510 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1d520 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1d530 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1d540 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1d550 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1d560 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1d570 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1d580 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1d590 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1d5a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1d5b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1d5c0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1d5d0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1d5e0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1d5f0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1d600 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1d610 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1d620 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1d630 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1d640 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1d650 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1d660 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1d670 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1d680 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1d690 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1d6a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1d6b0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1d6c0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1d6d0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1d6e0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1d6f0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1d700 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1d710 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1d720 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1d730 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1d740 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1d750 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1d760 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1d770 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d780 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1d790 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1d7a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1d7b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1d7c0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1d7d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1d7e0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1d7f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d800 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1d810 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1d820 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1d830 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1d840 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1d850 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1d860 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1d870 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d880 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1d890 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1d8a0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1d8b0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1d8c0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1d8d0 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1d8e0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1d8f0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1d900 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1d910 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1d920 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1d930 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1d940 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1d950 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1d960 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1d970 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1d980 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1d990 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1d9a0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1d9b0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1d9c0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1d9d0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1d9e0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1d9f0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1da00 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1da10 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1da20 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1da30 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1da40 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1da50 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1da60 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1da70 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1da80 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
1da90 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
1daa0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1dab0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
1dac0 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
1dad0 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
1dae0 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
1daf0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
1db00 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
1db10 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
1db20 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
1db30 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
1db40 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
1db50 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
1db60 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
1db70 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
1db80 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
1db90 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1dba0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
1dbb0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
1dbc0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1dbd0 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
1dbe0 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
1dbf0 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
1dc00 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1dc10 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1dc20 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1dc30 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1dc40 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1dc50 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1dc60 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1dc70 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
1dc80 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1dc90 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1dca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1dcb0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1dcc0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1dcd0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
1dce0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1dcf0 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1dd00 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1dd10 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1dd20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1dd30 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1dd40 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1dd50 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1dd60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1dd70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1dd80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1dd90 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1dda0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1ddb0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1ddc0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1ddd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1dde0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1ddf0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1de00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1de10 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1de20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1de30 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1de40 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1de50 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1de60 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1de70 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1de80 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1de90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1dea0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1deb0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1dec0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1ded0 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1dee0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1def0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1df00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1df10 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1df20 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1df30 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1df40 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1df50 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1df60 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1df70 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1df80 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1df90 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1dfa0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1dfb0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1dfc0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1dfd0 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1dfe0 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1dff0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e000 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1e010 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1e020 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1e030 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1e040 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1e050 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1e060 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e070 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1e080 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1e090 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1e0a0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1e0b0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1e0c0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1e0d0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1e0e0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e0f0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1e100 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1e110 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1e120 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1e130 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1e140 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1e150 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1e160 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1e170 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1e180 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1e190 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1e1a0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1e1b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1e1c0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1e1d0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1e1e0 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1e1f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1e200 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1e210 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1e220 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1e230 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1e240 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1e250 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1e260 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1e270 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1e280 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1e290 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1e2a0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1e2b0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1e2c0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1e2d0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1e2e0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1e2f0 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1e300 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1e310 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1e320 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1e330 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1e340 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1e350 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1e360 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1e370 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1e380 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1e390 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1e3a0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1e3b0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1e3c0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1e3d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1e3e0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1e3f0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1e400 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1e410 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1e420 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1e430 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1e440 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1e450 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1e460 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1e470 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1e480 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1e490 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1e4a0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1e4b0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1e4c0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1e4d0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1e4e0 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1e4f0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1e500 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1e510 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1e520 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1e530 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1e540 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1e550 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1e560 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1e570 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1e580 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1e590 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1e5a0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1e5b0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1e5c0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1e5d0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1e5e0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1e5f0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1e600 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1e610 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1e620 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1e630 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1e640 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1e650 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1e660 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1e670 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1e680 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1e690 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1e6a0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1e6b0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1e6c0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1e6d0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1e6e0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1e6f0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1e700 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1e710 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1e720 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1e730 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1e740 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1e750 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1e760 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1e770 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1e780 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1e790 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1e7a0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1e7b0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1e7c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1e7d0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1e7e0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1e7f0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1e800 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1e810 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1e820 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1e830 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1e840 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1e850 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1e860 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1e870 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1e880 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1e890 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1e8a0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1e8b0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1e8c0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1e8d0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1e8e0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1e8f0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1e900 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1e910 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1e920 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1e930 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1e940 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1e950 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1e960 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1e970 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1e980 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1e990 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1e9a0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1e9b0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1e9c0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1e9d0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1e9e0 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1e9f0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1ea00 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1ea10 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1ea20 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1ea30 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1ea40 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1ea50 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1ea60 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1ea70 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1ea80 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1ea90 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1eaa0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1eab0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1eac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1ead0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1eae0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1eaf0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1eb00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1eb10 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1eb20 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1eb30 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1eb40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1eb50 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1eb60 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1eb70 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1eb80 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1eb90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eba0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1ebb0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1ebc0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1ebd0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1ebe0 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1ebf0 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1ec00 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1ec10 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1ec20 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1ec30 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1ec40 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1ec50 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1ec60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ec70 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1ec80 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1ec90 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1eca0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1ecb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ecc0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1ecd0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1ece0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ecf0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1ed00 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1ed10 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1ed20 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1ed30 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1ed40 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1ed50 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1ed60 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1ed70 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1ed80 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1ed90 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1eda0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1edb0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1edc0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1edd0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1ede0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
1edf0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ee00 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1ee10 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1ee20 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1ee30 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1ee40 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1ee50 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1ee60 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1ee70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ee80 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1ee90 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1eea0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1eeb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1eec0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eed0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1eee0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1eef0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1ef00 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1ef10 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1ef20 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1ef30 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1ef40 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1ef50 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1ef60 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1ef70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1ef80 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1ef90 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1efa0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1efb0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1efc0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1efd0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1efe0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1eff0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
1f000 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
1f010 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
1f020 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1f030 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1f040 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1f050 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1f060 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1f070 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1f080 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1f090 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f0a0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1f0b0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1f0c0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1f0d0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1f0e0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1f0f0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1f100 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1f110 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1f120 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1f130 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1f140 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1f150 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1f160 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1f170 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1f180 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1f190 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1f1a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1f1b0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1f1c0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1f1d0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1f1e0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1f1f0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1f200 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1f210 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1f220 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1f230 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1f240 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1f250 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1f260 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1f270 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1f280 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1f290 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1f2a0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1f2b0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1f2c0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1f2d0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1f2e0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1f2f0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1f300 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1f310 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1f320 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1f330 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1f340 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1f350 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1f360 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1f370 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1f380 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1f390 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1f3a0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1f3b0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1f3c0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1f3d0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1f3e0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1f3f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1f400 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1f410 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1f420 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1f430 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1f440 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1f450 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1f460 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1f470 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1f480 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1f490 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1f4a0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1f4b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f4c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f4d0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1f4e0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1f4f0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1f500 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1f510 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1f520 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1f530 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f540 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f550 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1f560 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1f570 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f580 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f590 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f5a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1f5b0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1f5c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f5d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f5e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f5f0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1f600 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1f610 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f620 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f640 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1f650 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1f660 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1f670 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f690 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1f6a0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1f6b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1f6c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f6d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f6e0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1f6f0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1f700 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f710 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f720 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f730 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1f740 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1f750 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f760 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f780 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1f790 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1f7a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f7b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f7c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f7d0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1f7e0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1f7f0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1f800 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f810 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f820 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1f830 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1f840 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f850 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f860 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f870 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1f880 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1f890 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1f8a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f8b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f8c0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1f8d0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1f8e0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1f8f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f900 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f910 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1f920 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1f930 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1f940 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f950 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1f960 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1f970 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1f980 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f990 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f9a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1f9b0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1f9c0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1f9d0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1f9e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f9f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1fa00 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1fa10 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1fa20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fa30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fa40 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1fa50 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1fa60 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1fa70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1fa80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fa90 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1faa0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1fab0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1fac0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1fad0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1fae0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1faf0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1fb00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fb10 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1fb20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fb30 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1fb40 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1fb50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fb60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1fb70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fb80 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1fb90 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1fba0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1fbb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fbc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fbd0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1fbe0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1fbf0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1fc00 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1fc10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fc20 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1fc30 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1fc40 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1fc50 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fc60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fc70 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1fc80 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1fc90 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1fca0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1fcb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1fcc0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1fcd0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1fce0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1fcf0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1fd00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1fd10 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1fd20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1fd30 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1fd40 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1fd50 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1fd60 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1fd70 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1fd80 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1fd90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fda0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fdb0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1fdc0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1fdd0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1fde0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1fdf0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1fe00 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1fe10 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1fe20 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1fe30 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1fe40 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1fe50 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1fe60 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1fe70 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1fe80 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1fe90 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
1fea0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
1feb0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1fec0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
1fed0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
1fee0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
1fef0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
1ff00 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
1ff10 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
1ff20 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
1ff30 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
1ff40 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1ff50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ff60 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
1ff70 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
1ff80 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
1ff90 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1ffa0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
1ffb0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1ffc0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
1ffd0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
1ffe0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
1fff0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
20000 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
20010 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
20020 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20030 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
20040 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20050 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
20060 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
20070 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
20080 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
20090 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
200a0 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
200b0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
200c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
200d0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
200e0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
200f0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
20100 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
20110 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
20120 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
20130 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
20140 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20150 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
20160 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
20170 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
20180 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
20190 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
201a0 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
201b0 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
201c0 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
201d0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
201e0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
201f0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
20200 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
20210 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
20220 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
20230 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
20240 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
20250 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
20260 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
20270 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
20280 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
20290 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
202a0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
202b0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
202c0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
202d0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
202e0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
202f0 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
20300 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
20310 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
20320 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
20330 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
20340 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
20350 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
20360 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
20370 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
20380 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
20390 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
203a0 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
203b0 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
203c0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
203d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
203e0 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
203f0 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
20400 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
20410 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
20420 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
20430 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
20440 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
20450 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
20460 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
20470 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
20480 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
20490 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
204a0 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
204b0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
204c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
204d0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
204e0 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
204f0 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
20500 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
20510 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
20520 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
20530 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
20540 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
20550 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
20560 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
20570 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
20580 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
20590 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
205a0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
205b0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
205c0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
205d0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
205e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
205f0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
20600 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
20610 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
20620 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
20630 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
20640 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
20650 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
20660 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
20670 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
20680 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
20690 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
206a0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
206b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
206c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
206d0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
206e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
206f0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
20700 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
20710 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
20720 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
20730 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
20740 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
20750 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
20760 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
20770 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
20780 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20790 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
207a0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
207b0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
207c0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
207d0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
207e0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
207f0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
20800 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
20810 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
20820 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
20830 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
20840 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
20850 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
20860 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
20870 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
20880 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
20890 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
208a0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
208b0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
208c0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
208d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
208e0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
208f0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
20900 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
20910 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
20920 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
20930 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
20940 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
20950 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
20960 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
20970 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
20980 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
20990 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
209a0 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
209b0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
209c0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
209d0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
209e0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
209f0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
20a00 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
20a10 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
20a20 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
20a30 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
20a40 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
20a50 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
20a60 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20a70 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
20a80 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
20a90 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
20aa0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
20ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
20ac0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
20ad0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
20ae0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
20af0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20b00 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
20b10 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
20b20 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
20b30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20b40 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
20b50 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
20b60 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
20b70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
20b80 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
20b90 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
20ba0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
20bb0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
20bc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
20bd0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
20be0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
20bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
20c00 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
20c10 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
20c20 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
20c30 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
20c40 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
20c50 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
20c60 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
20c70 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
20c80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
20c90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
20ca0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
20cb0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
20cc0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
20cd0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
20ce0 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
20cf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20d00 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
20d10 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
20d20 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
20d30 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
20d40 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
20d50 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
20d60 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
20d70 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
20d80 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
20d90 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
20da0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
20db0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
20dc0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
20dd0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
20de0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
20df0 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
20e00 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
20e10 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
20e20 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
20e30 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
20e40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
20e50 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
20e60 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
20e70 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
20e80 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
20e90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
20ea0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
20eb0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
20ec0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
20ed0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
20ee0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
20ef0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
20f00 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
20f10 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
20f20 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
20f30 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
20f40 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
20f50 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
20f60 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  g will be UTF-8 
20f70 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72  for databases cr
20f80 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73  eated using.** s
20f90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
20fa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20fb0 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  ().  ^The defaul
20fc0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64  t encoding for d
20fd0 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61  atabases.** crea
20fe0 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ted using sqlite
20ff0 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20  3_open16() will 
21000 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  be UTF-16 in the
21010 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
21020 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  er..**.** Whethe
21030 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
21040 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
21050 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
21060 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
21070 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
21080 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21090 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
210a0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
210b0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
210c0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
210d0 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
210e0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
210f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
21100 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
21110 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
21120 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
21130 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
21140 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
21150 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
21160 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
21170 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
21180 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
21190 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
211a0 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
211b0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
211c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
211d0 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
211e0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
211f0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
21200 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
21210 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
21220 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
21230 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
21240 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
21250 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
21260 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b  AREDCACHE],.** [
21270 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
21280 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f  ATECACHE], and/o
21290 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  r [SQLITE_OPEN_U
212a0 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  RI] flags:)^.**.
212b0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
212c0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
212d0 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
212e0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
212f0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
21300 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
21310 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
21320 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
21330 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
21340 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
21350 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
21360 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
21370 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
21380 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
21390 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
213a0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
213b0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
213c0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
213d0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
213e0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
213f0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
21400 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
21410 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
21420 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
21430 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
21440 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
21450 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
21460 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
21470 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
21480 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
21490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
214a0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
214b0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
214c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
214d0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
214e0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69  and is created i
214f0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
21500 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
21510 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
21520 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
21530 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
21540 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
21550 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
21560 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
21570 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
21580 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
21590 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
215a0 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
215b0 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
215c0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
215d0 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  ve optionally co
215e0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65  mbined with othe
215f0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  r.** [SQLITE_OPE
21600 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c  N_READONLY | SQL
21610 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d  ITE_OPEN_* bits]
21620 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
21630 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
21640 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
21650 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
21660 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
21670 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
21680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21690 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
216a0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
216b0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
216c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
216d0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
216e0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
216f0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
21700 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
21710 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
21720 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
21730 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
21740 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
21750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21760 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
21770 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
21780 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
21790 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
217a0 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
217b0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
217c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
217d0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
217e0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
217f0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
21800 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
21810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21820 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
21830 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
21840 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
21850 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
21860 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
21870 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
21880 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
21890 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
218a0 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
218b0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
218c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
218d0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
218e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
218f0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
21900 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
21910 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
21920 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
21930 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
21940 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
21950 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21960 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
21970 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
21980 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
21990 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
219a0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
219b0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
219c0 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
219d0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
219e0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
219f0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75  se.  ^If the fou
21a00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
21a10 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
21a20 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
21a30 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
21a40 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
21a50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21a60 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
21a70 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
21a80 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
21a90 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
21aa0 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
21ab0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
21ac0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
21ad0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
21ae0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
21af0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
21b00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
21b10 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
21b20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
21b30 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
21b40 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
21b50 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
21b60 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
21b70 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
21b80 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
21b90 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
21ba0 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
21bb0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
21bc0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
21bd0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
21be0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
21bf0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
21c00 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
21c10 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
21c20 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
21c30 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
21c40 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
21c50 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
21c60 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
21c70 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
21c80 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
21c90 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
21ca0 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
21cb0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
21cc0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
21cd0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
21ce0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
21cf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21d00 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
21d10 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   [[URI filenames
21d20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
21d30 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c  ()]] <h3>URI Fil
21d40 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  enames</h3>.**.*
21d50 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e  * ^If [URI filen
21d60 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74  ame] interpretat
21d70 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20  ion is enabled, 
21d80 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  and the filename
21d90 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67   argument.** beg
21da0 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22  ins with "file:"
21db0 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e  , then the filen
21dc0 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74  ame is interpret
21dd0 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52  ed as a URI. ^UR
21de0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e  I.** filename in
21df0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
21e00 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b  enabled if the [
21e10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
21e20 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20   flag is.** set 
21e30 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  in the fourth ar
21e40 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
21e50 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20  3_open_v2(), or 
21e60 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65  if it has.** bee
21e70 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c  n enabled global
21e80 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ly using the [SQ
21e90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
21ea0 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65   option with the
21eb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
21ec0 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72  fig()] method or
21ed0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
21ee0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65  USE_URI] compile
21ef0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
21f00 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   As of SQLite ve
21f10 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49  rsion 3.7.7, URI
21f20 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
21f30 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
21f40 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
21f50 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
21f60 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
21f70 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
21f80 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
21f90 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21fa0 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
21fb0 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
21fc0 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
21fd0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
21fe0 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
21ff0 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
22000 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
22010 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
22020 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
22030 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
22040 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
22050 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
22060 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
22070 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
22080 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
22090 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
220a0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
220b0 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
220c0 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
220d0 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
220e0 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
220f0 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
22100 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
22110 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
22120 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
22130 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
22140 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
22150 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
22160 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
22170 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
22180 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
22190 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
221a0 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
221b0 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
221c0 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
221d0 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
221e0 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
221f0 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
22200 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
22210 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
22220 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
22230 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
22240 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
22250 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
22260 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
22270 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
22280 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
22290 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
222a0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
222b0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
222c0 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
222d0 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
222e0 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
222f0 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
22300 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
22310 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
22320 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
22330 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
22340 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
22350 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
22360 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
22370 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
22380 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
22390 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
223a0 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
223b0 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
223c0 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
223d0 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
223e0 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
223f0 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
22400 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
22410 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
22420 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
22430 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
22440 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
22450 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
22460 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
22470 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
22480 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
22490 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
224a0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
224b0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
224c0 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
224d0 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
224e0 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
224f0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
22500 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
22510 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
22520 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
22530 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
22540 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
22550 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
22560 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
22570 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
22580 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
22590 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
225a0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
225b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
225c0 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
225d0 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
225e0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
225f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
22600 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22610 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
22620 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
22630 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
22640 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
22650 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
22660 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
22670 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
22680 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
22690 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
226a0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
226b0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
226c0 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
226d0 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
226e0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
226f0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
22700 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
22710 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
22720 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
22730 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
22740 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
22750 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
22760 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
22770 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22780 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
22790 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
227a0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
227b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
227c0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
227d0 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
227e0 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
227f0 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
22800 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
22810 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
22820 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
22830 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
22840 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
22850 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
22860 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
22870 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
22880 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
22890 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
228a0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
228b0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
228c0 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
228d0 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
228e0 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
228f0 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
22900 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
22910 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
22920 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
22930 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
22940 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
22950 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
22960 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
22970 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
22980 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
22990 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
229a0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
229b0 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
229c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
229d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
229e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
229f0 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
22a00 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
22a10 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
22a20 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
22a30 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
22a40 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
22a50 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
22a60 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
22a70 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
22a80 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
22a90 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
22aa0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
22ab0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
22ac0 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
22ad0 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
22ae0 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
22af0 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
22b00 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
22b10 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
22b20 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
22b30 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22b40 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
22b50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22b60 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
22b70 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
22b80 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
22b90 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
22ba0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
22bb0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
22bc0 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
22bd0 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
22be0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
22bf0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
22c00 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
22c10 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
22c20 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
22c30 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
22c40 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
22c50 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
22c60 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
22c70 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
22c80 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
22c90 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
22ca0 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
22cb0 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
22cc0 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
22cd0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
22ce0 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
22cf0 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
22d00 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
22d10 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
22d20 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
22d30 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
22d40 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
22d50 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
22d60 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
22d70 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
22d80 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
22d90 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
22da0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
22db0 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
22dc0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
22dd0 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
22de0 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
22df0 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
22e00 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
22e10 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
22e20 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
22e30 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
22e40 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
22e50 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
22e60 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
22e70 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
22e80 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
22e90 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
22ea0 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
22eb0 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
22ec0 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
22ed0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
22ee0 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
22ef0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
22f00 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
22f10 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
22f20 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
22f30 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
22f40 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
22f50 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
22f60 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
22f70 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
22f80 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
22f90 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
22fa0 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
22fb0 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
22fc0 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
22fd0 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
22fe0 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
22ff0 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
23000 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
23010 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
23020 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
23030 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
23040 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
23050 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
23060 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
23070 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
23080 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
23090 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
230a0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
230b0 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
230c0 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
230d0 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
230e0 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
230f0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
23100 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
23110 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
23120 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
23130 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
23140 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
23150 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
23160 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
23170 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
23180 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
23190 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
231a0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
231b0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
231c0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
231d0 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
231e0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
231f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
23200 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
23210 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
23220 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
23230 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
23240 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
23250 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
23260 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
23270 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
23280 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
23290 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
232a0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
232b0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
232c0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
232d0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
232e0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
232f0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
23300 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
23310 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
23320 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
23330 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
23340 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
23350 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
23360 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
23370 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
23380 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
23390 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
233a0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
233b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
233c0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
233d0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
233e0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
233f0 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
23400 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
23410 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
23420 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
23430 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
23440 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
23450 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
23460 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
23470 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
23480 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
23490 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
234a0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
234b0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
234c0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
234d0 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
234e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
234f0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
23500 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
23510 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
23520 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
23530 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
23540 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
23550 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
23560 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
23570 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
23580 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
23590 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
235a0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
235b0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
235c0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
235d0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
235e0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
235f0 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
23600 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
23610 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
23620 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
23630 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
23640 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
23650 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
23660 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
23670 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
23680 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
23690 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
236a0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
236b0 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
236c0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
236d0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
236e0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
236f0 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
23700 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
23710 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
23720 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
23730 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
23740 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
23750 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
23760 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
23770 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
23780 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
23790 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
237a0 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
237b0 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
237c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
237d0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
237e0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
237f0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
23800 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
23810 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
23820 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
23830 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
23840 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
23850 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23860 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
23870 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
23880 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
23890 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
238a0 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
238b0 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
238c0 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
238d0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
238e0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
238f0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
23900 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
23910 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
23920 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
23930 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
23940 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
23950 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23960 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
23970 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
23980 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
23990 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
239a0 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
239b0 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
239c0 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
239d0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
239e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
239f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
23a00 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
23a10 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
23a20 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
23a30 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
23a40 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
23a50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
23a60 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
23a70 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
23a80 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
23a90 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
23aa0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
23ab0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
23ac0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
23ad0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
23ae0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
23af0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
23b00 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
23b10 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
23b20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
23b30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23b40 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
23b50 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
23b60 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
23b70 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
23b80 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
23b90 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
23ba0 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
23bb0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
23bc0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
23bd0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
23be0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
23bf0 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
23c00 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
23c10 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
23c20 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
23c30 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
23c40 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73  ectory].*/.int s
23c50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
23c60 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
23c70 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
23c80 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
23c90 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
23ca0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
23cb0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
23cc0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
23cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
23ce0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
23cf0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
23d00 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
23d10 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
23d20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
23d30 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
23d40 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
23d50 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
23d60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
23d70 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
23d80 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
23d90 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
23da0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
23db0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
23dc0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
23dd0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
23de0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
23df0 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
23e00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
23e10 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
23e20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
23e30 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
23e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23e50 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
23e60 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
23e70 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
23e80 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
23e90 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
23ea0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
23eb0 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
23ec0 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
23ed0 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
23ee0 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
23ef0 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
23f00 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
23f10 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
23f20 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
23f30 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
23f40 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
23f50 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
23f60 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
23f70 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
23f80 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
23f90 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
23fa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23fb0 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
23fc0 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
23fd0 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
23fe0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
23ff0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
24000 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
24010 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
24020 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
24030 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
24040 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
24050 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
24060 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
24070 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
24080 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
24090 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
240a0 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
240b0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
240c0 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
240d0 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
240e0 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
240f0 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
24100 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
24110 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
24120 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
24130 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24140 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
24150 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
24160 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
24170 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24180 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
24190 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
241a0 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
241b0 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
241c0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
241d0 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
241e0 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
241f0 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
24200 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
24210 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
24220 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
24230 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
24240 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
24250 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
24260 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
24270 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
24280 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
24290 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
242a0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
242b0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
242c0 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
242d0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
242e0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
242f0 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
24300 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
24310 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
24320 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
24330 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
24340 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
24350 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
24360 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
24370 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
24380 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
24390 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
243a0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
243b0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
243c0 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
243d0 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
243e0 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
243f0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
24400 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
24410 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
24420 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
24430 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
24440 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
24450 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
24460 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
24470 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
24480 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
24490 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
244a0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
244b0 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
244c0 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
244d0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
244e0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
244f0 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
24500 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
24510 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
24520 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
24530 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
24540 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
24550 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
24560 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
24570 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
24580 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
24590 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
245a0 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
245b0 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
245c0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
245d0 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
245e0 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
245f0 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
24600 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
24610 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
24620 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
24630 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
24640 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  able..*/.const c
24650 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
24660 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
24670 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
24680 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
24690 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74  aram);.int sqlit
246a0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
246b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
246c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
246d0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
246e0 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  lt);.sqlite3_int
246f0 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
24700 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
24710 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
24720 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
24730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24740 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
24750 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
24760 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
24770 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
24780 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
24790 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
247a0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
247b0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
247c0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
247d0 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
247e0 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
247f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
24800 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
24810 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
24820 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
24830 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
24840 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
24850 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
24860 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
24870 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
24880 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
24890 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
248a0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
248b0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
248c0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
248d0 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
248e0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
248f0 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
24900 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
24910 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
24920 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
24930 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
24940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24950 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
24960 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
24970 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
24980 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
24990 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
249a0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
249b0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
249c0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
249d0 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
249e0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
249f0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
24a00 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
24a10 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
24a20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
24a30 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
24a40 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
24a50 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
24a60 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
24a70 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
24a80 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
24a90 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
24aa0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
24ab0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
24ac0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
24ad0 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
24ae0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24af0 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
24b00 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
24b10 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
24b20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
24b30 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
24b40 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
24b50 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
24b60 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
24b70 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
24b80 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
24b90 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
24ba0 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
24bb0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
24bc0 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
24bd0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
24be0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
24bf0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
24c00 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
24c10 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
24c20 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
24c30 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
24c40 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
24c50 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
24c60 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
24c70 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
24c80 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
24c90 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
24ca0 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
24cb0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
24cc0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
24cd0 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
24ce0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
24cf0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
24d00 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
24d10 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
24d20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
24d30 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
24d40 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
24d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
24d60 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
24d70 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
24d80 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
24d90 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
24da0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
24db0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
24dc0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
24dd0 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
24de0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
24df0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
24e00 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
24e10 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
24e20 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
24e30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
24e40 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
24e50 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
24e60 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
24e70 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
24e80 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
24e90 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
24ea0 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
24eb0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
24ec0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
24ed0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
24ee0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
24ef0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
24f00 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
24f10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
24f20 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
24f30 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
24f40 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24f50 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
24f60 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
24f70 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
24f80 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
24f90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24fa0 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
24fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
24fc0 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
24fd0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
24fe0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
24ff0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
25000 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
25010 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
25020 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
25030 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
25040 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
25050 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
25060 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
25070 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
25080 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
25090 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
250a0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
250b0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
250c0 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
250d0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
250e0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
250f0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
25100 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
25110 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
25120 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
25130 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
25140 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
25150 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
25160 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
25170 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
25180 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
25190 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
251a0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
251b0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
251c0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
251d0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
251e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
251f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
25200 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
25210 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
25220 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
25230 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
25240 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
25250 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
25260 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
25270 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
25280 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
25290 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
252a0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
252b0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
252c0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
252d0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
252e0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
252f0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
25300 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
25310 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
25320 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
25330 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
25340 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
25350 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
25360 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
25370 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
25380 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
25390 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
253a0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
253b0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
253c0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
253d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
253e0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
253f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25400 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
25410 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
25420 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
25430 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
25440 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
25450 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
25460 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
25470 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
25480 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
25490 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
254a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
254b0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
254c0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
254d0 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
254e0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
254f0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
25500 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
25510 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
25520 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
25530 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
25540 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
25550 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
25560 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
25570 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
25580 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
25590 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
255a0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
255b0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
255c0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
255d0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
255e0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
255f0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
25600 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
25610 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
25620 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
25630 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
25640 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
25650 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
25660 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
25670 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
25680 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
25690 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
256a0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
256b0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
256c0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
256d0 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
256e0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
256f0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
25700 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
25710 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
25720 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
25730 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
25740 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
25750 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
25760 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
25770 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
25780 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
25790 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
257a0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
257b0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
257c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
257d0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
257e0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
257f0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
25800 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
25810 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
25820 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
25830 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
25840 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
25850 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
25860 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
25870 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
25880 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
25890 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
258a0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
258b0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
258c0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
258d0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
258e0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
258f0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
25900 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
25910 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
25920 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
25930 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
25940 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
25950 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
25960 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
25970 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
25980 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
25990 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
259a0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
259b0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
259c0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
259d0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
259e0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
259f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
25a00 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
25a10 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
25a20 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
25a30 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
25a40 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
25a50 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
25a60 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
25a70 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
25a80 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
25a90 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
25aa0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
25ab0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
25ac0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
25ad0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
25ae0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
25af0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
25b00 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
25b10 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
25b20 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
25b30 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
25b40 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
25b50 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25b60 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
25b70 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
25b80 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
25b90 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
25ba0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
25bb0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
25bc0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
25bd0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
25be0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
25bf0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
25c00 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
25c10 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
25c20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
25c30 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
25c40 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
25c50 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
25c60 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
25c70 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
25c80 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
25c90 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25ca0 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
25cb0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
25cc0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
25cd0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
25ce0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
25cf0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
25d00 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
25d10 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
25d20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
25d30 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
25d40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
25d50 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25d60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
25d70 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
25d80 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
25d90 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
25da0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25db0 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
25dc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
25dd0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
25de0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
25df0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25e00 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
25e10 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
25e20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
25e30 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
25e40 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25e50 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
25e60 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
25e70 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
25e80 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
25e90 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25ea0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
25eb0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
25ec0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
25ed0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
25ee0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
25ef0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
25f00 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
25f10 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
25f20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25f30 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
25f40 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
25f50 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
25f60 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
25f70 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25f80 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
25f90 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
25fa0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
25fb0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
25fc0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
25fd0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
25fe0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
25ff0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
26000 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26010 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
26020 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
26030 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
26040 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
26050 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
26060 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
26070 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
26080 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
26090 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
260a0 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
260b0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
260c0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
260d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
260e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
260f0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
26100 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
26110 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
26120 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26130 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
26140 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
26150 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
26160 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26170 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
26180 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26190 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
261a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
261b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
261c0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
261d0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
261e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
261f0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
26200 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
26210 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26220 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
26230 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
26240 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
26250 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
26260 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
26270 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
26280 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
26290 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
262a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
262b0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
262c0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
262d0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
262e0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
262f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26300 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
26310 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
26320 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
26330 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
26340 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
26350 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
26360 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
26370 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
26380 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26390 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
263a0 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
263b0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
263c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
263d0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
263e0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
263f0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
26400 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
26410 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26420 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
26430 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
26440 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
26450 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26460 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
26470 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
26480 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
26490 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
264a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
264b0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
264c0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
264d0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
264e0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
264f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
26500 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
26510 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
26520 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
26530 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
26540 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
26550 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
26560 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
26570 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
26580 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
26590 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
265a0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
265b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
265c0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
265d0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
265e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
265f0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
26600 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
26610 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26620 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
26630 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
26640 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26650 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
26660 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
26670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26680 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
26690 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
266a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
266b0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
266c0 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
266d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
266e0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
266f0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
26700 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
26710 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
26720 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
26730 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
26740 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
26750 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
26760 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
26770 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
26780 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
26790 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
267a0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
267b0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
267c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
267d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
267e0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
267f0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
26800 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
26810 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
26820 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
26830 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
26840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26850 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
26860 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
26870 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
26880 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
26890 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
268a0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
268b0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
268c0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
268d0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
268e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
268f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
26900 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
26910 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
26920 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
26930 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
26940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26950 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
26960 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
26970 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
26980 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
26990 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
269a0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
269b0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
269c0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
269d0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
269e0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
269f0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
26a00 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
26a10 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
26a20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
26a30 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
26a40 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
26a50 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
26a60 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
26a70 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
26a80 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
26a90 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
26aa0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
26ab0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
26ac0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
26ad0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
26ae0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
26af0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
26b00 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
26b10 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
26b20 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
26b30 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
26b40 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
26b50 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
26b60 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
26b70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
26b80 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
26b90 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
26ba0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
26bb0 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
26bc0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
26bd0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
26be0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
26bf0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
26c00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
26c10 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
26c20 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
26c30 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
26c40 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
26c50 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
26c60 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
26c70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
26c80 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
26c90 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
26ca0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
26cb0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
26cc0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
26cd0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
26ce0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
26cf0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
26d00 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
26d10 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
26d20 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
26d30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26d40 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
26d50 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
26d60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
26d70 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
26d80 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
26d90 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
26da0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
26db0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
26dc0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
26dd0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
26de0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
26df0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
26e00 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
26e10 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
26e20 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
26e30 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
26e40 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
26e50 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
26e60 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
26e70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26e80 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
26e90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
26ea0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
26eb0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
26ec0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
26ed0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
26ee0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
26ef0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
26f00 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
26f10 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
26f20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
26f30 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
26f40 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
26f50 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
26f60 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26f70 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
26f80 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
26f90 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
26fa0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
26fb0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
26fc0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
26fd0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
26fe0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
26ff0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
27000 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
27010 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
27020 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
27030 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
27040 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
27050 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
27060 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
27070 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
27080 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
27090 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
270a0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
270b0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
270c0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
270d0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
270e0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
270f0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
27100 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
27110 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
27120 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
27130 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
27140 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
27150 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
27160 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
27170 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
27180 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
27190 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
271a0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
271b0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
271c0 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
271d0 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
271e0 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
271f0 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
27200 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
27210 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
27220 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
27230 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
27240 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
27250 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
27260 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27270 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
27280 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
27290 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
272a0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
272b0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
272c0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
272d0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
272e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
272f0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
27300 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
27310 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
27320 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
27330 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
27340 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
27350 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
27360 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
27370 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
27380 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
27390 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
273a0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
273b0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
273c0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
273d0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
273e0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
273f0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27400 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
27410 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
27420 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
27430 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
27440 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
27450 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
27460 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
27470 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
27480 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
27490 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
274a0 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
274b0 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
274c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
274d0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
274e0 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
274f0 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
27500 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
27510 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
27520 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
27530 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
27540 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
27550 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
27560 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
27570 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
27580 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
27590 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
275a0 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
275b0 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
275c0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
275d0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
275e0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
275f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
27600 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
27610 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
27620 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
27630 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
27640 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
27650 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
27660 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
27670 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
27680 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
27690 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
276a0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
276b0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
276c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
276d0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
276e0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
276f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
27700 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27710 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
27720 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
27730 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
27740 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
27750 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
27760 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
27770 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
27780 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
27790 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
277a0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
277b0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
277c0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
277d0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
277e0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
277f0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
27800 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
27810 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
27820 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
27830 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
27840 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
27850 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
27860 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
27870 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
27880 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
27890 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
278a0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
278b0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
278c0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
278d0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
278e0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
278f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
27900 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
27910 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
27920 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
27930 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
27940 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
27950 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27960 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
27970 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
27980 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
27990 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
279a0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
279b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
279c0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
279d0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
279e0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
279f0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
27a00 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
27a10 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
27a20 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
27a30 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
27a40 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27a50 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
27a60 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
27a70 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
27a80 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
27a90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
27aa0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
27ab0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
27ac0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
27ad0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27ae0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
27af0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
27b00 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
27b10 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27b20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27b30 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27b40 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27b50 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27b60 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
27b70 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
27b80 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
27b90 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
27ba0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
27bb0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
27bc0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
27bd0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
27be0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
27bf0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
27c00 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
27c10 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
27c20 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
27c30 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
27c40 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
27c50 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
27c60 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
27c70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27c80 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
27c90 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
27ca0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
27cb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27cc0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
27cd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
27ce0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
27cf0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
27d00 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
27d10 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
27d20 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
27d30 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
27d40 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
27d50 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
27d60 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
27d70 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
27d80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
27d90 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
27da0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
27db0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27dc0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
27dd0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
27de0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
27df0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
27e00 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
27e10 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
27e20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27e30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
27e40 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
27e50 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
27e60 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
27e70 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
27e80 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
27e90 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
27ea0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
27eb0 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
27ec0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
27ed0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
27ee0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
27ef0 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
27f00 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
27f10 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
27f20 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
27f30 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
27f40 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
27f50 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
27f60 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
27f70 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
27f80 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
27f90 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
27fa0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
27fb0 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
27fc0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
27fd0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
27fe0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27ff0 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
28000 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
28010 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
28020 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
28030 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
28040 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
28050 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
28060 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
28070 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
28080 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
28090 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
280a0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
280b0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
280c0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
280d0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
280e0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
280f0 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
28100 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
28110 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
28120 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
28130 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
28140 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
28150 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
28160 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
28170 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
28180 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
28190 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
281a0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
281b0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
281c0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
281d0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
281e0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
281f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
28200 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
28210 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
28220 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
28230 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
28240 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
28250 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
28260 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  sk..*/.int sqlit
28270 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
28280 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
28290 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
282a0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
282b0 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
282c0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
282d0 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
282e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
282f0 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
28300 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
28310 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
28320 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
28330 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
28340 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
28350 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
28360 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
28370 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
28380 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
28390 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
283a0 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
283b0 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
283c0 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
283d0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
283e0 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
283f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
28400 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
28410 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
28420 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
28430 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
28440 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
28450 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
28460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
28470 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
28480 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
28490 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
284a0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
284b0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
284c0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
284d0 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
284e0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
284f0 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
28500 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
28510 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
28520 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
28530 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
28540 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
28550 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
28560 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
28570 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
28580 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
28590 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
285a0 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
285b0 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
285c0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
285d0 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
285e0 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
285f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
28600 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
28610 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
28620 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
28630 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
28640 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
28650 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
28660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
28670 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28680 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
28690 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
286a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
286b0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
286c0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
286d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
286e0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
286f0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
28700 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
28710 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
28720 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
28730 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
28740 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
28750 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
28760 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
28770 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
28780 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
28790 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
287a0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
287b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
287c0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
287d0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
287e0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
287f0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
28800 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
28810 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
28820 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
28830 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
28840 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
28850 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
28860 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28870 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
28880 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
28890 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
288a0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
288b0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
288c0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
288d0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
288e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
288f0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
28900 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
28910 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
28920 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
28930 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
28940 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
28950 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
28960 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
28970 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28980 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
28990 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
289a0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
289b0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
289c0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
289d0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
289e0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
289f0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
28a00 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
28a10 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
28a20 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
28a30 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
28a40 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
28a50 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
28a60 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
28a70 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
28a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
28a90 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
28aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
28ab0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
28ac0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
28ad0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
28ae0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
28af0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
28b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28b10 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
28b20 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
28b30 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
28b40 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
28b50 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
28b60 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
28b70 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
28b80 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
28b90 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
28ba0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
28bb0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
28bc0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
28bd0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28be0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
28bf0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
28c00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
28c10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28c20 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
28c30 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
28c40 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
28c50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
28c60 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28c70 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28c80 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
28c90 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
28ca0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28cb0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
28cc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
28cd0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
28ce0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
28cf0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28d00 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
28d10 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
28d20 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
28d30 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
28d40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
28d50 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
28d60 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
28d70 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
28d80 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
28d90 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
28da0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
28db0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28dc0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
28dd0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
28de0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
28df0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
28e00 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
28e10 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
28e20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
28e30 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
28e40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
28e50 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
28e60 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
28e70 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
28e80 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
28e90 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
28ea0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
28eb0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
28ec0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
28ed0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
28ee0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
28ef0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
28f00 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28f10 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
28f20 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
28f30 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
28f40 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
28f50 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
28f60 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
28f70 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
28f80 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
28f90 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
28fa0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
28fb0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
28fc0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
28fd0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
28fe0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
28ff0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
29000 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
29010 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
29020 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
29030 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
29040 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
29050 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
29060 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
29070 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
29080 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
29090 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
290a0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
290b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
290c0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
290d0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
290e0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
290f0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
29100 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
29110 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
29120 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
29130 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
29140 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
29150 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
29160 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
29170 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
29180 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
29190 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
291a0 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
291b0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
291c0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
291d0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
291e0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
291f0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
29200 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
29210 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
29220 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
29230 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
29240 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
29250 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
29260 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
29270 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
29280 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
29290 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
292a0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
292b0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
292c0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
292d0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
292e0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
292f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29300 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
29310 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
29320 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
29330 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
29340 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
29350 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
29360 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
29370 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
29380 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
29390 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
293a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
293b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
293c0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
293d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
293e0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
293f0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
29400 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
29410 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
29420 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
29430 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
29440 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
29450 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
29460 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
29470 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
29480 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
29490 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
294a0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
294b0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
294c0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
294d0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
294e0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
294f0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
29500 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
29510 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29520 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
29530 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
29540 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
29550 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
29560 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
29570 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
29580 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
29590 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
295a0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
295b0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
295c0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
295d0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
295e0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
295f0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
29600 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
29610 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
29620 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
29630 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
29640 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
29650 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
29660 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
29670 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
29680 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
29690 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
296a0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
296b0 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
296c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
296d0 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
296e0 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
296f0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
29700 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
29710 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
29720 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
29730 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
29740 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
29750 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
29760 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
29770 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
29780 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
29790 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
297a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
297b0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
297c0 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
297d0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
297e0 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
297f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29800 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
29810 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
29820 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
29830 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
29840 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
29850 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
29860 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
29870 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
29880 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
29890 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
298a0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
298b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
298c0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
298d0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
298e0 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
298f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
29900 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
29910 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
29920 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
29930 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29940 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
29950 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
29960 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
29970 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e  nd_text64() then
29980 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74  .** that paramet
29990 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
299a0 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
299b0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
299c0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
299d0 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
299e0 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
299f0 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
29a00 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
29a10 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
29a20 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
29a30 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
29a40 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
29a50 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
29a60 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
29a70 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
29a80 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
29a90 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
29aa0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
29ab0 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
29ac0 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
29ad0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
29ae0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
29af0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
29b00 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f  ument to the BLO
29b10 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e  B and string bin
29b20 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a  ding interfaces.
29b30 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ** is a destruct
29b40 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
29b50 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
29b60 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
29b70 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
29b80 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
29b90 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
29ba0 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
29bb0 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
29bc0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
29bd0 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
29be0 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73  o bind API fails
29bf0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
29c00 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
29c10 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
29c20 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
29c30 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
29c40 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
29c50 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
29c60 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
29c70 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
29c80 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
29c90 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
29ca0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
29cb0 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
29cc0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
29cd0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
29ce0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
29cf0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
29d00 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
29d10 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
29d20 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
29d30 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
29d40 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
29d50 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72  ** ^The sixth ar
29d60 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
29d70 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
29d80 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a  must be one of.*
29d90 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  * [SQLITE_UTF8],
29da0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
29db0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
29dc0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
29dd0 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65  F16LE].** to spe
29de0 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e  cify the encodin
29df0 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e  g of the text in
29e00 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
29e10 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65  eter.  If.** the
29e20 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
29e30 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29e40 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20  text64() is not 
29e50 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c  one of the.** al
29e60 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f  lowed values sho
29e70 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20  wn above, or if 
29e80 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
29e90 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a  g is different.*
29ea0 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64  * from the encod
29eb0 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79  ing specified by
29ec0 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
29ed0 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62  eter, then the b
29ee0 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
29ef0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
29f00 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
29f10 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
29f20 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
29f30 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
29f40 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
29f50 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
29f60 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
29f70 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
29f80 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
29f90 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
29fa0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
29fb0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
29fc0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
29fd0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
29fe0 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
29ff0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2a000 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2a010 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2a020 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2a030 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2a040 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2a050 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2a060 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2a070 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2a080 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2a090 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2a0a0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2a0b0 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
2a0c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2a0d0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
2a0e0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
2a0f0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
2a100 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a110 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
2a120 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
2a130 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
2a140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2a150 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
2a160 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
2a170 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
2a180 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
2a190 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
2a1a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2a1b0 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
2a1c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
2a1d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
2a1e0 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
2a1f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2a200 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2a210 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
2a220 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2a230 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
2a240 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
2a250 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
2a260 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
2a270 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a280 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
2a290 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
2a2a0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
2a2b0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
2a2c0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2a2d0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
2a2e0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
2a2f0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
2a300 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2a310 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
2a320 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
2a330 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68  ITE_TOOBIG] migh
2a340 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66  t be returned if
2a350 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73   the size of a s
2a360 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a  tring or BLOB.**
2a370 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20   exceeds limits 
2a380 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69  imposed by [sqli
2a390 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2a3a0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2a3b0 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ) or.** [SQLITE_
2a3c0 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20  MAX_LENGTH]..** 
2a3d0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
2a3e0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
2a3f0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2a400 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2a410 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
2a420 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
2a430 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
2a440 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
2a450 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2a460 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2a470 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
2a480 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a490 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2a4a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a4b0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2a4c0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2a4d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
2a4e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2a4f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2a500 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
2a510 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2a520 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c  _bind_blob64(sql
2a530 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2a540 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71   const void*, sq
2a550 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2a560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a570 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
2a580 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
2a590 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2a5a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a5b0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
2a5c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2a5d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a5e0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
2a5f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
2a600 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2a610 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
2a620 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
2a630 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
2a640 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2a650 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2a660 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
2a670 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
2a680 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29  har*,int,void(*)
2a690 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
2a6a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2a6b0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a6c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2a6d0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2a6e0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2a6f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2a700 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a710 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
2a720 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2a730 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2a740 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28             void(
2a750 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67  *)(void*), unsig
2a760 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e  ned char encodin
2a770 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  g);.int sqlite3_
2a780 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
2a790 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2a7a0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
2a7b0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2a7c0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2a7d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a7e0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
2a7f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2a800 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2a810 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
2a820 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2a830 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
2a840 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
2a850 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
2a860 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
2a870 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
2a880 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
2a890 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
2a8a0 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
2a8b0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
2a8c0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
2a8d0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
2a8e0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
2a8f0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
2a900 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a910 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
2a920 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
2a930 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
2a940 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2a950 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
2a960 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
2a970 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
2a980 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
2a990 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
2a9a0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
2a9b0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
2a9c0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
2a9d0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
2a9e0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
2a9f0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
2aa00 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
2aa10 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
2aa20 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
2aa30 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
2aa40 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2aa50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2aa60 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2aa70 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2aa80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2aa90 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
2aaa0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2aab0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2aac0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2aad0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2aae0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2aaf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ab00 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
2ab10 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
2ab20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ab30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2ab40 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
2ab50 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
2ab60 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
2ab70 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
2ab80 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
2ab90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2aba0 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
2abb0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2abc0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
2abd0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2abe0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
2abf0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
2ac00 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
2ac10 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2ac20 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2ac30 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
2ac40 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2ac50 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
2ac60 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
2ac70 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
2ac80 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
2ac90 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
2aca0 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
2acb0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
2acc0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
2acd0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
2ace0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
2acf0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
2ad00 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
2ad10 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
2ad20 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
2ad30 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
2ad40 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2ad50 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
2ad60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
2ad70 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
2ad80 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
2ad90 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
2ada0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
2adb0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
2adc0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
2add0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
2ade0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
2adf0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
2ae00 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
2ae10 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
2ae20 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
2ae30 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2ae40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ae50 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
2ae60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ae70 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2ae80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2ae90 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2aea0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2aeb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2aec0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2aed0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2aee0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2aef0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
2af00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
2af10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2af20 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2af30 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
2af40 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
2af50 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
2af60 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
2af70 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2af80 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
2af90 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
2afa0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
2afb0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
2afc0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
2afd0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
2afe0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
2aff0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2b000 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2b010 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
2b020 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
2b030 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
2b040 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
2b050 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
2b060 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
2b070 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
2b080 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
2b090 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
2b0a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
2b0b0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
2b0c0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
2b0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b0e0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2b0f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2b100 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2b110 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2b120 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b130 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2b140 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2b150 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b160 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2b170 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b180 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b190 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
2b1a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2b1b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b1c0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
2b1d0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
2b1e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2b1f0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2b200 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2b210 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2b220 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2b230 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2b240 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b250 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2b260 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2b270 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2b280 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2b290 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2b2a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2b2b0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
2b2c0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2b2d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2b2e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2b2f0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
2b300 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
2b310 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
2b320 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
2b330 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2b340 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
2b350 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2b360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b370 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
2b380 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2b390 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
2b3a0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
2b3b0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
2b3c0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
2b3d0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
2b3e0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
2b3f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
2b400 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2b410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b420 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2b430 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2b440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2b450 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
2b460 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
2b470 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2b480 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2b490 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
2b4a0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
2b4b0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
2b4c0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2b4d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
2b4e0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2b4f0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
2b500 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b510 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2b520 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2b530 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
2b540 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2b550 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
2b560 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2b570 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2b580 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
2b590 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
2b5a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2b5b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b5c0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
2b5d0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
2b5e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2b5f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2b600 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2b610 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
2b620 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2b630 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
2b640 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
2b650 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
2b660 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
2b670 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
2b680 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b690 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
2b6a0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
2b6b0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2b6c0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2b6d0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2b6e0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2b6f0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2b700 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b710 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2b720 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2b730 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
2b740 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
2b750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2b760 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2b770 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
2b780 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
2b790 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2b7a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2b7b0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2b7c0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2b7d0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2b7e0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2b7f0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2b800 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2b810 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2b820 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2b830 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2b840 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2b850 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2b860 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2b870 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2b880 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2b890 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2b8a0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2b8b0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2b8c0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2b8d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2b8e0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2b8f0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2b900 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2b910 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2b920 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
2b930 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b940 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
2b950 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b960 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
2b970 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b980 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2b990 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2b9a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b9b0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2b9c0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2b9d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2b9e0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2b9f0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2ba00 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2ba10 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2ba20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2ba30 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2ba40 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2ba50 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2ba60 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2ba70 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2ba80 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2ba90 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2baa0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2bab0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2bac0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2bad0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2bae0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2baf0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2bb00 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2bb10 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2bb20 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2bb30 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2bb40 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2bb50 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2bb60 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2bb70 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2bb80 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2bb90 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2bba0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bbb0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2bbc0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2bbd0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2bbe0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2bbf0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2bc00 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2bc10 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2bc20 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2bc30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2bc40 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2bc50 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2bc60 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2bc70 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2bc80 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2bc90 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2bca0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2bcb0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2bcc0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2bcd0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2bce0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2bcf0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2bd00 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2bd10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2bd20 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2bd30 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2bd40 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2bd50 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2bd60 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2bd70 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2bd80 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2bd90 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2bda0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2bdb0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2bdc0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2bdd0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2bde0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2bdf0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2be00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2be10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2be20 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2be30 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2be40 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2be50 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2be60 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2be70 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2be80 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2be90 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2bea0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2beb0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2bec0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2bed0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2bee0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2bef0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2bf00 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2bf10 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2bf20 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2bf30 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2bf40 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2bf50 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2bf60 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2bf70 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2bf80 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2bf90 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2bfa0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2bfb0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2bfc0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2bfd0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2bfe0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2bff0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2c000 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2c010 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2c020 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2c030 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2c040 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2c050 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2c060 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2c070 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2c080 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2c090 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2c0a0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2c0b0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2c0c0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2c0d0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2c0e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2c0f0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2c100 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2c110 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2c120 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2c130 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2c140 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2c150 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2c160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2c170 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2c180 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2c190 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2c1a0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2c1b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c1c0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2c1d0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2c1e0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2c1f0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2c200 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
2c210 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2c220 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2c230 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c240 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2c250 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c260 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
2c270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2c280 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
2c290 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c2a0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
2c2b0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2c2c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2c2d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2c2e0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2c2f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2c300 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2c310 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2c320 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c330 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2c340 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c350 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
2c360 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c370 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c380 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
2c390 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
2c3a0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
2c3b0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2c3c0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
2c3d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c3e0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
2c3f0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
2c400 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
2c410 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2c420 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
2c430 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
2c440 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
2c450 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
2c460 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
2c470 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2c480 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
2c490 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
2c4a0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
2c4b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
2c4c0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2c4d0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2c4e0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
2c4f0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2c500 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
2c510 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2c520 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
2c530 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2c540 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
2c550 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
2c560 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
2c570 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
2c580 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
2c590 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
2c5a0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
2c5b0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
2c5c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
2c5d0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
2c5e0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
2c5f0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
2c600 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
2c610 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
2c620 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
2c630 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
2c640 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
2c650 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
2c660 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
2c670 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
2c680 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
2c690 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
2c6a0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2c6b0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
2c6c0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
2c6d0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
2c6e0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
2c6f0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
2c700 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
2c710 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
2c720 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
2c730 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
2c740 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
2c750 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
2c760 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
2c770 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
2c780 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
2c790 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
2c7a0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
2c7b0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
2c7c0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
2c7d0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
2c7e0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
2c7f0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
2c800 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2c810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2c820 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
2c830 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2c840 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2c850 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2c860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2c870 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2c880 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2c890 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2c8a0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2c8b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c8c0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2c8d0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2c8e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2c8f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2c900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c910 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2c920 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2c930 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2c940 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2c950 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2c960 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2c970 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2c980 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2c990 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2c9a0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2c9b0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2c9c0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2c9d0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2c9e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2c9f0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2ca00 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2ca10 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2ca20 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2ca30 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2ca40 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2ca50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ca60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2ca70 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2ca80 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2ca90 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2caa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2cab0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2cac0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2cad0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2cae0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2caf0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2cb00 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2cb10 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2cb20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2cb30 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2cb40 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2cb50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2cb60 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2cb70 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2cb80 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2cb90 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2cba0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2cbb0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2cbc0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2cbd0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2cbe0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2cbf0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2cc00 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2cc10 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2cc20 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2cc30 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2cc40 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2cc50 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2cc60 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2cc70 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2cc80 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2cc90 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2cca0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2ccb0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2ccc0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2ccd0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2cce0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2ccf0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2cd00 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2cd10 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2cd20 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2cd30 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2cd40 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2cd50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2cd60 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2cd70 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2cd80 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2cd90 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2cda0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2cdb0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2cdc0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2cdd0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2cde0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2cdf0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2ce00 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2ce10 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2ce20 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2ce30 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2ce40 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2ce50 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2ce60 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2ce70 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2ce80 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2ce90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2cea0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2ceb0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2cec0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2ced0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2cee0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2cef0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2cf00 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2cf10 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2cf20 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2cf30 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2cf40 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2cf50 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2cf60 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2cf70 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2cf80 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2cf90 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2cfa0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2cfb0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2cfc0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2cfd0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2cfe0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2cff0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2d000 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2d010 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2d020 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2d030 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2d040 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2d050 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2d060 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2d070 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2d080 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2d090 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2d0a0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2d0b0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2d0c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2d0d0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2d0e0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2d0f0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2d100 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2d110 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2d120 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2d130 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2d140 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2d150 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2d160 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2d170 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2d180 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2d190 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2d1a0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2d1b0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2d1c0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2d1d0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2d1e0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2d1f0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2d200 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2d210 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2d220 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2d230 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2d240 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2d250 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2d260 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2d270 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2d280 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2d290 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2d2a0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2d2b0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2d2c0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2d2d0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2d2e0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2d2f0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2d300 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2d310 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2d320 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2d330 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2d340 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2d350 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2d360 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2d370 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2d380 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2d390 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2d3a0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2d3b0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2d3c0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2d3d0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2d3e0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2d3f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d400 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2d410 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2d420 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2d430 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2d440 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2d450 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2d460 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2d470 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2d480 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2d490 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2d4a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d4b0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2d4c0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2d4d0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2d4e0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2d4f0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2d500 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2d510 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2d520 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2d530 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2d540 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2d550 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2d560 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2d570 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2d580 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2d590 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2d5a0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2d5b0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2d5c0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2d5d0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2d5e0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2d5f0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2d600 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2d610 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2d620 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2d630 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2d640 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2d650 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2d660 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2d670 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2d680 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2d690 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2d6a0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2d6b0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2d6c0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2d6d0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2d6e0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2d6f0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2d700 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2d710 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2d720 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2d730 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2d740 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2d750 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2d760 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2d770 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2d780 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2d790 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d7a0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2d7b0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2d7c0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2d7d0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2d7e0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2d7f0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2d800 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2d810 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2d820 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2d830 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2d840 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2d850 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2d860 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2d870 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2d880 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2d890 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2d8a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d8b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2d8c0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2d8d0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2d8e0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2d8f0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2d900 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2d910 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2d920 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2d930 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2d940 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2d950 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2d960 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2d970 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2d980 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2d990 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2d9a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d9b0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
2d9c0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2d9d0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
2d9e0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
2d9f0 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
2da00 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2da10 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
2da20 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
2da30 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2da40 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
2da50 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2da60 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
2da70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2da80 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
2da90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
2daa0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
2dab0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
2dac0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
2dad0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
2dae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
2daf0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
2db00 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
2db10 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
2db20 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2db30 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
2db40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2db50 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2db60 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
2db70 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
2db80 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
2db90 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2dba0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2dbb0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
2dbc0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
2dbd0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2dbe0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
2dbf0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2dc00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2dc10 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
2dc20 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
2dc30 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
2dc40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2dc50 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2dc60 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
2dc70 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
2dc80 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
2dc90 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
2dca0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
2dcb0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
2dcc0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
2dcd0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
2dce0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
2dcf0 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
2dd00 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
2dd10 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2dd20 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
2dd30 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
2dd40 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
2dd50 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2dd60 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2dd70 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
2dd80 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
2dd90 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
2dda0 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
2ddb0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
2ddc0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
2ddd0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
2dde0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
2ddf0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2de00 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
2de10 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
2de20 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
2de30 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2de40 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
2de50 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
2de60 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
2de70 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
2de80 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
2de90 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
2dea0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
2deb0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2dec0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
2ded0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
2dee0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
2def0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
2df00 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
2df10 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
2df20 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
2df30 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
2df40 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
2df50 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
2df60 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
2df70 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
2df80 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
2df90 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
2dfa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2dfb0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
2dfc0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
2dfd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2dfe0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
2dff0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
2e000 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
2e010 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
2e020 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
2e030 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
2e040 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
2e050 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
2e060 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
2e070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e080 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
2e090 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
2e0a0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
2e0b0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2e0c0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
2e0d0 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
2e0e0 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74  "result set" int
2e0f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  erface..**.** ^T
2e100 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2e110 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2e120 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
2e130 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
2e140 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
2e150 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
2e160 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
2e170 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2e180 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2e190 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2e1a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2e1b0 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2e1c0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2e1d0 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2e1e0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2e1f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2e200 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2e210 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2e220 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2e230 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2e240 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2e250 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2e260 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2e270 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2e280 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
2e290 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2e2a0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2e2b0 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2e2c0 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
2e2d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2e2e0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
2e2f0 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
2e300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e310 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
2e320 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2e330 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2e340 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2e350 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2e360 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2e370 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2e380 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2e390 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2e3a0 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2e3b0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2e3c0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2e3d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2e3e0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e3f0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2e400 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2e410 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2e420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e430 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2e440 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2e450 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2e460 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2e470 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2e480 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2e490 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2e4a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2e4b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2e4c0 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2e4d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2e4e0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2e4f0 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2e500 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2e510 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2e520 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2e530 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2e540 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2e550 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2e560 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e570 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2e580 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2e590 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2e5a0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2e5b0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2e5c0 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2e5d0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2e5e0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2e5f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e600 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
2e610 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
2e620 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2e630 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
2e640 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
2e650 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
2e660 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
2e670 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2e680 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
2e690 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2e6a0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
2e6b0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2e6c0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
2e6d0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
2e6e0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
2e6f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2e700 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e710 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
2e720 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
2e730 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
2e740 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
2e750 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
2e760 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
2e770 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
2e780 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
2e790 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2e7a0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2e7b0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
2e7c0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
2e7d0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
2e7e0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
2e7f0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
2e800 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
2e810 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
2e820 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
2e830 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e840 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2e850 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2e860 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2e870 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2e880 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2e890 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2e8a0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2e8b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2e8c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2e8d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
2e8e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2e8f0 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
2e900 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2e910 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
2e920 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2e930 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2e940 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2e950 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2e960 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2e970 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e980 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2e990 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2e9a0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2e9b0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
2e9c0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2e9d0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2e9e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2e9f0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2ea00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2ea10 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2ea20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ea30 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2ea40 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2ea50 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2ea60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
2ea70 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2ea80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2ea90 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2eaa0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2eab0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2eac0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2ead0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2eae0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
2eaf0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2eb00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2eb10 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2eb20 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2eb30 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
2eb40 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2eb50 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2eb60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2eb70 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2eb80 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2eb90 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
2eba0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2ebb0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2ebc0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2ebd0 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
2ebe0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2ebf0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2ec00 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2ec10 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2ec20 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2ec30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2ec40 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
2ec50 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2ec60 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
2ec70 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2ec80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ec90 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
2eca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ecb0 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
2ecc0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
2ecd0 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
2ece0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2ecf0 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
2ed00 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2ed10 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
2ed20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ed30 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
2ed40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ed50 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
2ed60 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2ed70 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2ed80 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2ed90 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2eda0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
2edb0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2edc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2edd0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
2ede0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
2edf0 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
2ee00 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
2ee10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2ee20 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
2ee30 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2ee40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2ee50 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2ee60 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
2ee70 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2ee80 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  ** ^The object r
2ee90 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2eea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2eeb0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
2eec0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2eed0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
2eee0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
2eef0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2ef00 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
2ef10 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
2ef20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2ef30 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2ef40 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2ef50 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2ef60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ef70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ef80 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2ef90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2efa0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2efb0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2efc0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2efd0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2efe0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2eff0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2f000 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f010 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2f020 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2f030 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
2f040 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2f050 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
2f060 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2f070 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2f080 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2f090 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2f0a0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2f0b0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2f0c0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2f0d0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2f0e0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2f0f0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2f100 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2f110 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2f120 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2f130 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2f140 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2f150 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2f160 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2f170 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2f180 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2f190 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2f1a0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2f1b0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2f1c0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2f1d0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2f1e0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2f1f0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2f200 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2f210 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2f220 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2f230 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2f240 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2f250 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2f260 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2f270 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2f280 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2f290 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
2f2a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2f2b0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2f2c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2f2d0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2f2e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2f2f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2f300 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
2f310 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2f320 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
2f330 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2f340 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2f350 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2f360 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2f370 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
2f380 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2f390 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
2f3a0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2f3b0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
2f3c0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2f3d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2f3e0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2f3f0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2f400 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2f410 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2f420 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2f430 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
2f440 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2f450 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
2f460 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2f470 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
2f480 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2f490 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2f4a0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
2f4b0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
2f4c0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
2f4d0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
2f4e0 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
2f4f0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2f500 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2f510 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
2f520 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2f530 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2f540 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2f550 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
2f560 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2f570 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2f580 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
2f590 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2f5a0 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
2f5b0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
2f5c0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
2f5d0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
2f5e0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2f5f0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  uote>)^.**.** Th
2f600 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
2f610 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
2f620 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
2f630 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
2f640 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
2f650 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
2f660 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
2f670 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2f680 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
2f690 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
2f6a0 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
2f6b0 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
2f6c0 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
2f6d0 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
2f6e0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
2f6f0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
2f700 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
2f710 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
2f720 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
2f730 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
2f740 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2f750 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
2f760 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
2f770 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
2f780 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f790 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
2f7a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
2f7b0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2f7c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2f7d0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
2f7e0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
2f7f0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
2f800 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
2f810 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
2f820 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
2f830 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
2f840 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
2f850 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2f860 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
2f870 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f880 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
2f890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f8a0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2f8b0 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
2f8c0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
2f8d0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
2f8e0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
2f8f0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
2f900 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2f910 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
2f920 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2f930 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
2f940 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2f950 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2f960 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2f970 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2f980 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2f990 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
2f9a0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2f9b0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2f9c0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
2f9d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2f9e0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2f9f0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2fa00 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
2fa10 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2fa20 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2fa30 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2fa40 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2fa50 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
2fa60 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
2fa70 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
2fa80 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
2fa90 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
2faa0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
2fab0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
2fac0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
2fad0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
2fae0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
2faf0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
2fb00 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
2fb10 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
2fb20 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2fb30 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2fb40 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2fb50 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2fb60 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2fb70 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2fb80 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2fb90 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2fba0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2fbb0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2fbc0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2fbd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2fbe0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2fbf0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2fc00 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2fc10 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2fc20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2fc30 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2fc40 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2fc50 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2fc60 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2fc70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2fc80 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2fc90 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2fca0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2fcb0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2fcc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2fcd0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2fce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2fcf0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2fd00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fd10 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2fd20 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2fd30 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2fd40 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2fd50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fd60 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2fd70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2fd80 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2fd90 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2fda0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2fdb0 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2fdc0 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2fdd0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2fde0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fdf0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2fe00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fe10 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2fe20 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2fe30 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2fe40 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2fe50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2fe60 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2fe70 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2fe80 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2fe90 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2fea0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2feb0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2fec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2fed0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2fee0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2fef0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2ff00 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
2ff10 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
2ff20 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
2ff30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2ff40 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
2ff50 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
2ff60 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
2ff70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2ff80 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2ff90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ffa0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
2ffb0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
2ffc0 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2ffd0 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2ffe0 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2fff0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
30000 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
30010 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
30020 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
30030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30040 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
30050 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
30060 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
30070 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
30080 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
30090 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
300a0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
300b0 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
300c0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
300d0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
300e0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
300f0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
30100 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
30110 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
30120 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
30130 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
30140 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
30150 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
30160 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
30170 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
30180 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
30190 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
301a0 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
301b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
301c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
301d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
301e0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
301f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
30200 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30210 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
30220 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30230 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
30240 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
30250 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
30260 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
30270 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
30280 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
30290 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
302a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
302b0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
302c0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
302d0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
302e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
302f0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
30300 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
30310 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
30320 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30330 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
30340 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30350 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30360 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30370 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
30380 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
30390 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
303a0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
303b0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
303c0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
303d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
303e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
303f0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
30400 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
30410 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
30420 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
30430 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
30440 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
30450 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
30460 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
30470 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
30480 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
30490 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
304a0 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
304b0 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
304c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
304d0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
304e0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
304f0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
30500 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
30510 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
30520 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
30530 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
30540 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
30550 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30560 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
30570 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
30580 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
30590 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
305a0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
305b0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
305c0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
305d0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
305e0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
305f0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
30600 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
30610 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
30620 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
30630 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
30640 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
30650 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
30660 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
30670 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
30680 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
30690 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
306a0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
306b0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
306c0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
306d0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
306e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
306f0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
30700 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
30710 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
30720 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
30730 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
30740 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
30750 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
30760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
30770 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
30780 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
30790 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
307a0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
307b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
307c0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
307d0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
307e0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
307f0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
30800 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
30810 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
30820 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
30830 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
30840 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
30850 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
30860 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
30870 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
30880 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
30890 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
308a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
308b0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
308c0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
308d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
308e0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
308f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
30900 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30910 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
30920 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
30930 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
30940 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
30950 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
30960 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
30970 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
30980 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
30990 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
309a0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
309b0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
309c0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
309d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
309e0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
309f0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
30a00 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
30a10 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
30a20 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
30a30 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
30a40 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
30a50 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
30a60 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
30a70 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
30a80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30a90 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
30aa0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
30ab0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
30ac0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
30ad0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
30ae0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30af0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
30b00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30b10 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
30b20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
30b30 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
30b40 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
30b50 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
30b60 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
30b70 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
30b80 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
30b90 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
30ba0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
30bb0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
30bc0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
30bd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
30be0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
30bf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30c00 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
30c10 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
30c20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
30c30 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
30c40 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
30c50 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
30c60 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
30c70 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
30c80 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
30c90 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
30ca0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
30cb0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
30cc0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
30cd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
30ce0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
30cf0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
30d00 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
30d10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
30d20 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
30d30 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
30d40 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
30d50 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
30d60 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
30d70 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
30d80 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
30d90 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
30da0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
30db0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
30dc0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
30dd0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
30de0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
30df0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
30e00 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
30e10 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
30e20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
30e30 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
30e40 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
30e50 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
30e60 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
30e70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
30e80 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
30e90 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
30ea0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
30eb0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
30ec0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
30ed0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
30ee0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
30ef0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
30f00 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
30f10 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
30f20 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
30f30 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
30f40 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
30f50 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
30f60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
30f70 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
30f80 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
30f90 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
30fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30fb0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
30fc0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
30fd0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
30fe0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
30ff0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
31000 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
31010 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
31020 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
31030 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31040 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
31050 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
31060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31070 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
31080 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
31090 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
310a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
310b0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
310c0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
310d0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
310e0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
310f0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
31100 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
31110 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
31120 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
31130 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
31140 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
31150 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
31160 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
31170 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
31180 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
31190 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
311a0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
311b0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
311c0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
311d0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
311e0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
311f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
31200 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
31210 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
31220 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
31230 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
31240 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
31250 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
31260 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
31270 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
31280 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
31290 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
312a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
312b0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
312c0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
312d0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
312e0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
312f0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
31300 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
31310 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
31320 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
31330 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
31340 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
31350 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
31360 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
31370 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
31380 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
31390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
313a0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
313b0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
313c0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
313d0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
313e0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
313f0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
31400 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
31410 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
31420 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
31430 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
31440 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
31450 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
31460 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
31470 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
31480 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
31490 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
314a0 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
314b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
314c0 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
314d0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
314e0 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
314f0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
31500 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
31510 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
31520 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31530 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
31540 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
31550 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
31560 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
31570 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
31580 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
31590 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
315a0 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
315b0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
315c0 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
315d0 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
315e0 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
315f0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
31600 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
31610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
31620 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
31630 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
31640 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
31650 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
31660 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
31670 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
31680 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
31690 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
316a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
316b0 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
316c0 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
316d0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
316e0 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
316f0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
31700 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
31710 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
31720 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
31730 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
31740 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
31750 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
31760 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
31770 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
31780 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
31790 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
317a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
317b0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
317c0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
317d0 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
317e0 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
317f0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
31800 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
31810 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
31820 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
31830 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
31840 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
31850 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
31860 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
31870 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
31880 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
31890 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
318a0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
318b0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
318c0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
318d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
318e0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
318f0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
31900 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
31910 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
31920 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
31930 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
31940 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
31950 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
31960 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
31970 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
31980 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
31990 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
319a0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
319b0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
319c0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
319d0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
319e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
319f0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
31a00 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
31a10 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
31a20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
31a30 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
31a40 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
31a50 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
31a60 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
31a70 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
31a80 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
31a90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31aa0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
31ab0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
31ac0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
31ad0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
31ae0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
31af0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
31b00 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
31b10 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
31b20 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
31b30 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
31b40 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
31b50 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
31b60 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
31b70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31b80 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
31b90 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
31ba0 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
31bb0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
31bc0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
31bd0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
31be0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
31bf0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
31c00 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
31c10 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
31c20 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
31c30 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
31c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31c50 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
31c60 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
31c70 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
31c80 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
31c90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31ca0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
31cb0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
31cc0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
31cd0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
31ce0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
31cf0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
31d00 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
31d10 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
31d20 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
31d30 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31d40 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
31d50 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
31d60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31d70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31d80 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
31d90 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
31da0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
31db0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
31dc0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
31dd0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
31de0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
31df0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
31e00 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
31e10 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
31e20 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
31e30 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
31e40 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
31e50 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
31e60 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
31e70 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
31e80 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
31e90 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
31ea0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
31eb0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
31ec0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
31ed0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
31ee0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
31ef0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
31f00 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
31f10 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
31f20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31f30 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
31f40 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
31f50 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
31f60 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
31f70 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
31f80 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
31f90 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
31fa0 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
31fb0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
31fc0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
31fd0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
31fe0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
31ff0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
32000 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
32010 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
32020 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
32030 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
32040 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
32050 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
32060 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
32070 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
32080 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
32090 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
320a0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
320b0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
320c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
320d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
320e0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
320f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32100 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
32110 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
32120 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
32130 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
32140 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
32150 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
32160 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
32170 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
32180 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
32190 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
321a0 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
321b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
321c0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
321d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
321e0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
321f0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
32200 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
32210 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
32220 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
32230 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
32240 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
32250 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32260 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
32270 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
32280 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
32290 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
322a0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
322b0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
322c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
322d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
322e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
322f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32300 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
32310 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
32320 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
32330 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
32340 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
32350 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
32360 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32370 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32380 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
32390 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
323a0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
323b0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
323c0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
323d0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
323e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
323f0 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
32400 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
32410 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
32420 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
32430 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
32440 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
32450 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
32460 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32470 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
32480 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
32490 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
324a0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
324b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
324c0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
324d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
324e0 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
324f0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
32500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32510 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
32520 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
32530 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
32540 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
32550 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
32560 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
32570 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
32580 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
32590 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
325a0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
325b0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
325c0 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
325d0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
325e0 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
325f0 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
32600 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
32610 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
32620 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
32630 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
32640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32650 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
32660 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
32670 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
32680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
32690 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
326a0 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
326b0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
326c0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
326d0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
326e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
326f0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
32700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
32710 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
32720 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
32730 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
32740 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
32750 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
32760 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
32770 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
32780 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
32790 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
327a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
327b0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
327c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
327d0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
327e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
327f0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
32800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
32810 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
32820 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
32830 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
32840 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
32850 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
32860 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
32870 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
32880 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
32890 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
328a0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
328b0 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
328c0 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
328d0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
328e0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
328f0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
32900 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
32910 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
32920 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
32930 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
32940 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
32950 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
32960 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
32970 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
32980 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
32990 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
329a0 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
329b0 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
329c0 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
329d0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
329e0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
329f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32a00 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
32a10 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
32a20 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
32a30 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
32a40 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
32a50 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
32a60 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
32a70 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
32a80 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
32a90 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
32aa0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
32ab0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
32ac0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
32ad0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
32ae0 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
32af0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32b00 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
32b10 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
32b20 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
32b30 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
32b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32b50 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
32b60 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
32b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32b80 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
32b90 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
32ba0 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
32bb0 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
32bc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32bd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
32be0 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
32bf0 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
32c00 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
32c10 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
32c20 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
32c30 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
32c40 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
32c50 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
32c60 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
32c70 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
32c80 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
32c90 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
32ca0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
32cb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
32cc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32cd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
32ce0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
32cf0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
32d00 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
32d10 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
32d20 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
32d30 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
32d40 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
32d50 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
32d60 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
32d70 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
32d80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32d90 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
32da0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
32db0 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
32dc0 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
32dd0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32de0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
32df0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
32e00 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
32e10 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
32e20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32e30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
32e40 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
32e50 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
32e60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32e70 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
32e80 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
32e90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
32ea0 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
32eb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32ec0 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
32ed0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
32ee0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
32ef0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
32f00 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
32f10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
32f20 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
32f30 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
32f40 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20  cept that these 
32f50 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
32f60 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
32f70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32f80 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
32f90 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
32fa0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
32fb0 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
32fc0 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
32fd0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
32fe0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
32ff0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
33000 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
33010 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
33020 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
33030 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
33040 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
33050 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
33060 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
33070 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
33080 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
33090 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
330a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
330b0 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
330c0 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
330d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
330e0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
330f0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
33100 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
33110 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
33120 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
33130 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
33140 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
33150 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
33160 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
33170 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
33180 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
33190 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
331a0 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
331b0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
331c0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
331d0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
331e0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
331f0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
33200 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
33210 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
33220 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
33230 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
33240 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
33250 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
33260 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
33270 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
33280 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
33290 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
332a0 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
332b0 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
332c0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
332d0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
332e0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
332f0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
33300 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
33310 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
33320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33330 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
33340 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33350 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
33360 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
33370 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
33380 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
33390 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
333a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
333b0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
333c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
333d0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
333e0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
333f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
33400 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
33410 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33420 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
33430 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33440 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
33450 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
33460 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
33470 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
33480 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
33490 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
334a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
334b0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
334c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
334d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
334e0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
334f0 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
33500 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
33510 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
33520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
33530 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
33540 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
33550 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
33560 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
33570 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
33580 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
33590 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
335a0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
335b0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
335c0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
335d0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
335e0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
335f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
33600 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
33610 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
33620 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33630 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
33640 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33650 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
33660 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
33670 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
33680 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
33690 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
336a0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
336b0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
336c0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
336d0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
336e0 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
336f0 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
33700 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
33710 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
33720 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
33730 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
33740 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
33750 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
33760 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
33770 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33780 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
33790 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
337a0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
337b0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
337c0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
337d0 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
337e0 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
337f0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
33800 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
33810 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
33820 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
33830 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
33840 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
33850 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33860 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
33870 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
33880 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
33890 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
338a0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
338b0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
338c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
338d0 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
338e0 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
338f0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
33900 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
33910 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
33920 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
33930 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
33940 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
33950 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
33960 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
33970 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
33980 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
33990 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
339a0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
339b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
339c0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
339d0 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
339e0 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
339f0 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
33a00 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
33a10 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
33a20 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
33a30 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
33a40 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
33a50 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
33a60 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
33a70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33a80 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
33a90 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
33aa0 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
33ab0 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
33ac0 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
33ad0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
33ae0 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
33af0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
33b00 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
33b10 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
33b20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
33b30 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
33b40 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33b50 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
33b60 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
33b70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
33b80 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
33b90 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
33ba0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
33bb0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
33bc0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
33bd0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
33be0 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
33bf0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
33c00 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
33c10 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
33c20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
33c30 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
33c40 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
33c50 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
33c60 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
33c70 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
33c80 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
33c90 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
33ca0 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
33cb0 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
33cc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
33cd0 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
33ce0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
33cf0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
33d00 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
33d10 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
33d20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
33d30 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
33d40 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
33d50 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
33d60 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
33d70 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
33d80 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
33d90 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
33da0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
33db0 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
33dc0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
33dd0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
33de0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
33df0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
33e00 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
33e10 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
33e20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
33e30 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
33e40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
33e50 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
33e60 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
33e70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
33e80 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
33e90 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
33ea0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
33eb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33ec0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
33ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
33ee0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
33ef0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
33f00 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
33f10 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
33f20 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
33f30 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
33f40 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
33f50 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
33f60 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
33f70 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
33f80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33f90 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
33fa0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
33fb0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
33fc0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
33fd0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
33fe0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
33ff0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
34000 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
34010 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
34020 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
34030 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
34040 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
34050 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34060 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
34070 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
34080 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
34090 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
340a0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
340b0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
340c0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
340d0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
340e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
340f0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
34100 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34110 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
34120 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
34130 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34140 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
34150 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
34160 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34170 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34180 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
34190 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
341a0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
341b0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
341c0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
341d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
341e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
341f0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
34200 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
34210 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
34220 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
34230 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
34240 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
34250 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ta.**.** These f
34260 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
34270 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
34280 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
34290 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
342a0 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
342b0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
342c0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
342d0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
342e0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
342f0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
34300 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
34310 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
34320 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
34330 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
34340 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
34350 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
34360 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
34370 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
34380 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
34390 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
343a0 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
343b0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
343c0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
343d0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
343e0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
343f0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
34400 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
34410 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
34420 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
34430 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
34440 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
34450 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72  ng as the patter
34460 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73  n string remains
34470 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68   the same,.** th
34480 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
34490 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
344a0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
344b0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
344c0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
344d0 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  me function..**.
344e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
344f0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
34500 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
34510 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
34520 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
34530 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
34540 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34550 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
34560 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
34570 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
34580 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34590 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
345a0 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  . ^If there is n
345b0 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  o metadata.** as
345c0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
345d0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  e function argum
345e0 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65  ent, this sqlite
345f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
34600 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
34610 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
34620 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
34630 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34640 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74  ata(C,N,P,X) int
34650 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61  erface saves P a
34660 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  s metadata for t
34670 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
34680 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
34690 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
346a0 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65  unction.  ^Subse
346b0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
346c0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
346d0 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72  xdata(C,N) retur
346e0 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73  n P from the mos
346f0 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69  t recent.** sqli
34700 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34710 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66  C,N,P,X) call if
34720 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
34730 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a   still valid or.
34740 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d  ** NULL if the m
34750 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
34760 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e   discarded..** ^
34770 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20  After each call 
34780 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
34790 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
347a0 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e  where X is not N
347b0 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ULL,.** SQLite w
347c0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
347d0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
347e0 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65  on X with parame
347f0 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a  ter P exactly.**
34800 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20   once, when the 
34810 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63  metadata is disc
34820 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  arded..** SQLite
34830 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63   is free to disc
34840 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61  ard the metadata
34850 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e   at any time, in
34860 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a  cluding: <ul>.**
34870 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63   <li> when the c
34880 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
34890 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
348a0 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c  changes, or.** <
348b0 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  li> when [sqlite
348c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
348d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
348e0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  )] is called for
348f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c   the.**      SQL
34900 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a   statement, or.*
34910 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69  * <li> when sqli
34920 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34930 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61  ) is invoked aga
34940 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70  in on the same p
34950 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20  arameter, or.** 
34960 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20  <li> during the 
34970 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33  original sqlite3
34980 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63  _set_auxdata() c
34990 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72  all when a memor
349a0 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63  y .**      alloc
349b0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
349c0 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  rs. </ul>)^.**.*
349d0 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20  * Note the last 
349e0 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63  bullet in partic
349f0 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72  ular.  The destr
34a00 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73  uctor X in .** s
34a10 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34a20 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68  ta(C,N,P,X) migh
34a30 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65  t be called imme
34a40 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
34a50 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  the.** sqlite3_s
34a60 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
34a70 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75  erface even retu
34a80 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69  rns.  Hence sqli
34a90 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34aa0 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63  ).** should be c
34ab0 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65  alled near the e
34ac0 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nd of the functi
34ad0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
34ae0 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e  n and the.** fun
34af0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
34b00 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
34b10 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20  make any use of 
34b20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74  P after.** sqlit
34b30 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
34b40 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
34b50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
34b60 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
34b70 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
34b80 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
34b90 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74  lls for.** funct
34ba0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ion parameters t
34bb0 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d  hat are compile-
34bc0 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20  time constants, 
34bd0 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61  including litera
34be0 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
34bf0 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64  [parameters] and
34c00 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d   expressions com
34c10 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73  posed from the s
34c20 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ame.)^.**.** The
34c30 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
34c40 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
34c50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
34c60 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
34c70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
34c80 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
34c90 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
34ca0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
34cb0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
34cc0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
34cd0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
34ce0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
34cf0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
34d00 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
34d10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
34d20 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
34d30 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
34d40 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
34d50 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
34d60 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
34d70 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
34d80 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
34d90 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
34da0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
34db0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
34dc0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
34dd0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
34de0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
34df0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
34e00 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
34e10 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
34e20 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
34e30 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
34e40 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
34e50 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
34e60 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
34e70 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
34e80 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
34e90 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
34ea0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
34eb0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
34ec0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
34ed0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
34ee0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
34ef0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
34f00 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
34f10 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
34f20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
34f30 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
34f40 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
34f50 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
34f60 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
34f70 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65  mpilers..*/.type
34f80 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
34f90 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
34fa0 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
34fb0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
34fc0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
34fd0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
34fe0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
34ff0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
35000 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
35010 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
35020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
35030 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
35040 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
35050 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
35060 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
35070 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
35080 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
35090 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
350a0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
350b0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
350c0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
350d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
350e0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
350f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35100 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
35110 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
35120 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
35130 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
35140 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
35150 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
35160 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
35170 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
35180 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
35190 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
351a0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
351b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
351c0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
351d0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
351e0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
351f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
35200 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
35210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35220 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
35230 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
35240 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
35250 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35260 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35270 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
35280 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
35290 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
352a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
352b0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
352c0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
352d0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
352e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
352f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35300 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
35310 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
35320 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
35330 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
35340 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35350 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
35360 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
35370 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
35380 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
35390 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
353a0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
353b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
353c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
353d0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
353e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
353f0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
35400 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
35410 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35420 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
35430 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
35440 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
35450 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
35460 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
35470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35480 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
35490 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
354a0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
354b0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
354c0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
354d0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
354e0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
354f0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
35500 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
35510 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
35520 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
35530 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35540 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
35550 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
35560 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
35570 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
35580 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
35590 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
355a0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
355b0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
355c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
355d0 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
355e0 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
355f0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
35600 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35610 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
35620 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
35630 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
35640 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
35650 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
35660 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
35670 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
35680 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
35690 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
356a0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
356b0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
356c0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
356d0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
356e0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
356f0 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
35700 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
35710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35720 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
35730 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35740 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
35750 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
35760 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
35770 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
35780 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
35790 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
357a0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
357b0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
357c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
357d0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
357e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
357f0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
35800 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
35810 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
35820 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
35830 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
35840 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
35850 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
35860 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
35870 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
35880 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
35890 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
358a0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
358b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
358c0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
358d0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
358e0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
358f0 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
35900 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
35910 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
35920 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
35930 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
35940 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
35950 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
35960 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
35970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35980 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
35990 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
359a0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
359b0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
359c0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
359d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
359e0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
359f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
35a00 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
35a10 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
35a20 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
35a30 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
35a40 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
35a50 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
35a60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35a70 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
35a80 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
35a90 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
35aa0 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
35ab0 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
35ac0 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
35ad0 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
35ae0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35af0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
35b00 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
35b10 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
35b20 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
35b30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35b40 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
35b50 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
35b60 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
35b70 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
35b80 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
35b90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35ba0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
35bb0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
35bc0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
35bd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35be0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35bf0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
35c00 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
35c10 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
35c20 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
35c30 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
35c40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
35c50 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
35c60 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
35c70 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
35c80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35c90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35ca0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
35cb0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35cc0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
35cd0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
35ce0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
35cf0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
35d00 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
35d10 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
35d20 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
35d30 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35d40 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
35d50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35d60 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
35d70 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
35d80 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
35d90 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
35da0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
35db0 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
35dc0 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
35dd0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
35de0 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
35df0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
35e00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28  3_result_text64(
35e10 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35e20 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35e30 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  e of an.** appli
35e40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35e50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
35e60 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20 61  text string in a
35e70 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70  n encoding.** sp
35e80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
35e90 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29 20  ifth (and last) 
35ea0 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
35eb0 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20   must be one.** 
35ec0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
35ed0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
35ee0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
35ef0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
35f00 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c  TF16LE]..** ^SQL
35f10 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
35f20 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
35f30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
35f40 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
35f50 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
35f60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35f70 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
35f80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
35f90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35fa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35fb0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35fc0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
35fd0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
35fe0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
35ff0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
36000 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
36010 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
36020 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
36030 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
36040 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
36050 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36060 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
36070 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
36080 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
36090 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
360a0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
360b0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
360c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
360d0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
360e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
360f0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
36100 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
36110 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36120 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
36130 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
36140 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
36150 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
36160 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
36170 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
36180 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
36190 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
361a0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
361b0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
361c0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
361d0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
361e0 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
361f0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
36200 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
36210 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
36220 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
36230 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
36240 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
36250 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
36260 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
36270 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
36280 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
36290 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
362a0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
362b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
362c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
362d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
362e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
362f0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
36300 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
36310 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
36320 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
36330 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
36340 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
36350 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
36360 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
36370 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
36380 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
36390 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
363a0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
363b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
363c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
363d0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
363e0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
363f0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
36400 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
36410 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
36420 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
36430 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
36440 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
36450 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
36460 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
36470 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
36480 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
36490 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
364a0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
364b0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
364c0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
364d0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
364e0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
364f0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
36500 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36510 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36520 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
36530 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
36540 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
36550 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
36560 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
36570 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
36580 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
36590 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
365a0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
365b0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
365c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
365d0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
365e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
365f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36600 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36610 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
36620 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
36630 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36640 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
36650 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
36660 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
36670 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
36680 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
36690 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
366a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
366b0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
366c0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
366d0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
366e0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
366f0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
36700 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
36710 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
36720 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
36730 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
36740 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
36750 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
36760 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
36770 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
36780 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36790 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
367a0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
367b0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
367c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
367d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
367e0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
367f0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
36800 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
36810 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
36820 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
36830 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
36840 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
36850 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
36860 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
36870 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
36880 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
36890 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
368a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
368b0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
368c0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
368d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
368e0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
368f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
36900 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
36910 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
36920 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36930 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
36940 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
36950 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
36960 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28  3_result_blob64(
36970 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36980 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 20  ,const void*,.  
36990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
369a0 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
369b0 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28  _uint64,void(*)(
369c0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
369d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
369e0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
369f0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
36a00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36a10 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
36a20 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
36a30 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
36a40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36a50 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
36a60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36a70 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
36a80 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36a90 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
36aa0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36ab0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36ac0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
36ad0 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
36ae0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
36af0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36b00 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
36b10 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
36b20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36b30 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
36b40 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
36b50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36b60 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
36b70 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
36b80 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
36b90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
36ba0 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
36bb0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
36bc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
36bd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36be0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
36bf0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
36c00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36c10 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73 71  result_text64(sq
36c20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36c30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
36c40 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
36c50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36c60 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
36c70 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
36c80 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
36c90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36ca0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(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 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, 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 31 36 6c 65 28 73 71 6c  ult_text16le(sql
36d00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36d10 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
36d20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36d30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36d40 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
36d50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36d60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
36d70 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
36d80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36d90 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
36da0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
36db0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
36dc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36dd0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
36de0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36df0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
36e00 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
36e10 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
36e20 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
36e30 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
36e40 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
36e50 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
36e60 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
36e70 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
36e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
36e90 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
36ea0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
36eb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
36ec0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
36ed0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
36ee0 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
36ef0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36f00 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
36f10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36f20 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
36f30 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
36f40 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36f50 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
36f60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
36f70 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
36f80 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
36f90 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
36fa0 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
36fb0 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
36fc0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
36fd0 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
36fe0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
36ff0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
37000 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
37010 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
37020 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
37030 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
37040 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
37050 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
37060 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
37070 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
37080 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
37090 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
370a0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
370b0 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
370c0 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
370d0 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
370e0 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
370f0 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
37100 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
37110 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37120 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
37130 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
37140 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
37150 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
37160 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
37170 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
37180 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
37190 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
371a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
371b0 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
371c0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
371d0 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
371e0 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
371f0 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
37200 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
37210 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
37220 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
37230 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
37240 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
37250 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
37260 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
37270 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
37280 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
37290 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
372a0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
372b0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
372c0 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
372d0 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
372e0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
372f0 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
37300 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
37310 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
37320 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
37330 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
37340 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
37350 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
37360 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
37370 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
37380 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
37390 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
373a0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
373b0 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
373c0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
373d0 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
373e0 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
373f0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
37400 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
37410 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
37420 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
37430 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
37440 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
37450 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
37460 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
37470 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
37480 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
37490 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
374a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
374b0 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
374c0 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
374d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
374e0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
374f0 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
37500 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
37510 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
37520 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
37530 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
37540 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
37550 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
37560 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
37570 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
37580 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
37590 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
375a0 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
375b0 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
375c0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
375d0 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
375e0 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
375f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
37600 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
37610 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
37620 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
37630 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
37640 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
37650 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
37660 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
37670 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
37680 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
37690 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
376a0 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
376b0 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
376c0 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
376d0 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
376e0 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
376f0 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
37700 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
37710 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
37720 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
37730 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
37740 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
37750 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
37760 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
37770 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
37780 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
37790 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
377a0 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
377b0 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
377c0 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
377d0 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
377e0 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
377f0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
37800 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
37810 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
37820 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
37830 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
37840 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
37850 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
37860 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
37870 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37880 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
37890 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
378a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
378b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
378c0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
378d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
378e0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
378f0 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
37900 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
37910 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
37920 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
37930 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
37940 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
37950 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
37960 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37970 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
37980 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
37990 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
379a0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
379b0 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
379c0 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
379d0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
379e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
379f0 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
37a00 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
37a10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
37a20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
37a30 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
37a40 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
37a50 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
37a60 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
37a70 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
37a80 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
37a90 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
37aa0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37ab0 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
37ac0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
37ad0 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
37ae0 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
37af0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
37b00 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
37b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
37b20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
37b30 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
37b40 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
37b50 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
37b60 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
37b70 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
37b80 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
37b90 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
37ba0 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
37bb0 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
37bc0 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
37bd0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
37be0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
37bf0 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
37c00 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
37c10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
37c20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
37c30 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
37c40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
37c50 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
37c60 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
37c70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37c80 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
37c90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37ca0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
37cb0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
37cc0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
37cd0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
37ce0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
37cf0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
37d00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
37d10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
37d20 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37d30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
37d40 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
37d50 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
37d60 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
37d70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
37d80 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
37d90 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
37da0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
37db0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
37dc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37dd0 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
37de0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
37df0 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
37e00 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
37e10 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
37e20 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
37e30 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
37e40 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
37e50 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
37e60 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
37e70 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
37e80 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
37e90 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
37ea0 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
37eb0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
37ec0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
37ed0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
37ee0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
37ef0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
37f00 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
37f10 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
37f20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
37f30 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
37f40 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
37f50 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
37f60 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
37f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
37f80 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
37f90 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
37fa0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
37fb0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
37fc0 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
37fd0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
37fe0 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
37ff0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
38000 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
38010 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
38020 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
38030 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
38040 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
38050 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
38060 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
38070 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
38080 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
38090 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
380a0 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
380b0 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
380c0 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
380d0 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
380e0 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
380f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
38100 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
38110 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
38120 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
38130 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
38140 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
38150 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
38160 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
38170 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
38180 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
38190 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
381a0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
381b0 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
381c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
381d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
381e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
381f0 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
38200 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
38210 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
38220 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
38230 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
38240 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
38250 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
38260 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
38270 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
38280 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
38290 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
382a0 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
382b0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
382c0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
382d0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
382e0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
382f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
38300 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
38310 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
38320 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
38330 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
38340 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
38350 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
38360 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
38370 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
38380 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
38390 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
383a0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
383b0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
383c0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
383d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
383e0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
383f0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
38400 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
38410 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
38420 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
38430 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
38440 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
38450 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
38460 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
38470 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
38480 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
38490 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
384a0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
384b0 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
384c0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
384d0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
384e0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
384f0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
38500 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
38510 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
38520 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
38530 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
38540 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
38550 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
38560 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
38570 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
38580 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
38590 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73   key */.);.int s
385a0 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20  qlite3_key_v2(. 
385b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
385c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
385d0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
385e0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
385f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
38600 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  me,           /*
38610 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   Name of the dat
38620 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
38630 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
38640 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
38650 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
38660 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
38670 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
38680 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
38690 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
386a0 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
386b0 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
386c0 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
386d0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
386e0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
386f0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
38700 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
38710 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
38720 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
38730 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
38740 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
38750 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
38760 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
38770 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
38780 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
38790 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
387a0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
387b0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
387c0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
387d0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
387e0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20  w key */.);.int 
387f0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32  sqlite3_rekey_v2
38800 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
38810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38820 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
38830 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
38840 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
38850 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20  bName,          
38860 20 2f 2a 20 4