Documentation Source Text

Hex Artifact Content
Login

Artifact 0bd272b4d60d7770c4d50984858d04602ef49f41:


0000: 3c 3f 78 6d 6c 20 76 65 72 73 69 6f 6e 3d 22 31  <?xml version="1
0010: 2e 30 22 20 65 6e 63 6f 64 69 6e 67 3d 22 57 69  .0" encoding="Wi
0020: 6e 64 6f 77 73 2d 31 32 35 32 22 3f 3e 0a 3c 74  ndows-1252"?>.<t
0030: 69 74 6c 65 3e 53 51 4c 69 74 65 20 43 68 61 6e  itle>SQLite Chan
0040: 67 65 73 20 46 72 6f 6d 20 56 65 72 73 69 6f 6e  ges From Version
0050: 20 33 2e 34 2e 32 20 54 6f 20 33 2e 35 2e 30 3c   3.4.2 To 3.5.0<
0060: 2f 74 69 74 6c 65 3e 0a 3c 74 63 6c 3e 0a 70 72  /title>.<tcl>.pr
0070: 6f 63 20 43 4f 44 45 20 7b 74 65 78 74 7d 20 7b  oc CODE {text} {
0080: 0a 20 20 68 64 5f 70 75 74 73 20 22 3c 62 6c 6f  .  hd_puts "<blo
0090: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 22 0a 20  ckquote><pre>". 
00a0: 20 68 64 5f 70 75 74 73 20 24 74 65 78 74 0a 20   hd_puts $text. 
00b0: 20 68 64 5f 70 75 74 73 20 22 3c 2f 70 72 65 3e   hd_puts "</pre>
00c0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 22 0a 7d  </blockquote>".}
00d0: 0a 70 72 6f 63 20 50 41 52 41 47 52 41 50 48 20  .proc PARAGRAPH 
00e0: 7b 74 65 78 74 7d 20 7b 0a 20 20 68 64 5f 72 65  {text} {.  hd_re
00f0: 73 6f 6c 76 65 20 3c 70 3e 24 74 65 78 74 3c 2f  solve <p>$text</
0100: 70 3e 5c 6e 0a 7d 0a 73 65 74 20 6c 65 76 65 6c  p>\n.}.set level
0110: 28 30 29 20 30 0a 73 65 74 20 6c 65 76 65 6c 28  (0) 0.set level(
0120: 31 29 20 30 0a 70 72 6f 63 20 48 45 41 44 49 4e  1) 0.proc HEADIN
0130: 47 20 7b 6e 20 6e 61 6d 65 20 7b 74 61 67 20 7b  G {n name {tag {
0140: 7d 7d 7d 20 7b 0a 20 20 69 66 20 7b 24 74 61 67  }}} {.  if {$tag
0150: 21 3d 22 22 7d 20 7b 0a 20 20 20 20 68 64 5f 66  !=""} {.    hd_f
0160: 72 61 67 6d 65 6e 74 20 24 74 61 67 0a 20 20 7d  ragment $tag.  }
0170: 0a 20 20 67 6c 6f 62 61 6c 20 6c 65 76 65 6c 0a  .  global level.
0180: 20 20 69 6e 63 72 20 6c 65 76 65 6c 28 24 6e 29    incr level($n)
0190: 0a 20 20 66 6f 72 20 7b 73 65 74 20 69 20 5b 65  .  for {set i [e
01a0: 78 70 72 20 7b 24 6e 2b 31 7d 5d 7d 20 7b 24 69  xpr {$n+1}]} {$i
01b0: 3c 31 30 7d 20 7b 69 6e 63 72 20 69 7d 20 7b 0a  <10} {incr i} {.
01c0: 20 20 20 20 73 65 74 20 6c 65 76 65 6c 28 24 69      set level($i
01d0: 29 20 30 0a 20 20 7d 0a 20 20 69 66 20 7b 24 6e  ) 0.  }.  if {$n
01e0: 3d 3d 30 7d 20 7b 0a 20 20 20 20 73 65 74 20 6e  ==0} {.    set n
01f0: 75 6d 20 7b 7d 0a 20 20 7d 20 65 6c 73 65 69 66  um {}.  } elseif
0200: 20 7b 24 6e 3d 3d 31 7d 20 7b 0a 20 20 20 20 73   {$n==1} {.    s
0210: 65 74 20 6e 75 6d 20 24 6c 65 76 65 6c 28 31 29  et num $level(1)
0220: 2e 30 0a 20 20 7d 20 65 6c 73 65 20 7b 0a 20 20  .0.  } else {.  
0230: 20 20 73 65 74 20 6e 75 6d 20 24 6c 65 76 65 6c    set num $level
0240: 28 31 29 0a 20 20 20 20 66 6f 72 20 7b 73 65 74  (1).    for {set
0250: 20 69 20 32 7d 20 7b 24 69 3c 3d 24 6e 7d 20 7b   i 2} {$i<=$n} {
0260: 69 6e 63 72 20 69 7d 20 7b 0a 20 20 20 20 20 20  incr i} {.      
0270: 61 70 70 65 6e 64 20 6e 75 6d 20 2e 24 6c 65 76  append num .$lev
0280: 65 6c 28 24 69 29 0a 20 20 20 20 7d 0a 20 20 7d  el($i).    }.  }
0290: 0a 20 20 69 6e 63 72 20 6e 20 31 0a 20 20 68 64  .  incr n 1.  hd
02a0: 5f 70 75 74 73 20 22 3c 68 24 6e 3e 24 6e 75 6d  _puts "<h$n>$num
02b0: 20 24 6e 61 6d 65 3c 2f 68 24 6e 3e 22 0a 7d 0a   $name</h$n>".}.
02c0: 0a 68 64 5f 6b 65 79 77 6f 72 64 73 20 2a 33 34  .hd_keywords *34
02d0: 74 6f 33 35 0a 48 45 41 44 49 4e 47 20 30 20 7b  to35.HEADING 0 {
02e0: 4d 6f 76 69 6e 67 20 46 72 6f 6d 20 53 51 4c 69  Moving From SQLi
02f0: 74 65 20 33 2e 34 2e 32 20 74 6f 20 33 2e 35 2e  te 3.4.2 to 3.5.
0300: 30 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a  0}..PARAGRAPH {.
0310: 20 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e    SQLite version
0320: 20 33 2e 35 2e 30 20 69 6e 74 72 6f 64 75 63 65   3.5.0 introduce
0330: 73 20 61 20 6e 65 77 20 4f 53 20 69 6e 74 65 72  s a new OS inter
0340: 66 61 63 65 20 6c 61 79 65 72 20 74 68 61 74 0a  face layer that.
0350: 20 20 69 73 20 69 6e 63 6f 6d 70 61 74 69 62 6c    is incompatibl
0360: 65 20 77 69 74 68 20 61 6c 6c 20 70 72 69 6f 72  e with all prior
0370: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
0380: 69 74 65 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ite.  In additio
0390: 6e 2c 0a 20 20 61 20 66 65 77 20 65 78 69 73 74  n,.  a few exist
03a0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 68  ing interfaces h
03b0: 61 76 65 20 62 65 65 6e 20 67 65 6e 65 72 61 6c  ave been general
03c0: 69 7a 65 64 20 74 6f 20 77 6f 72 6b 20 61 63 72  ized to work acr
03d0: 6f 73 73 20 61 6c 6c 0a 20 20 64 61 74 61 62 61  oss all.  databa
03e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77  se connections w
03f0: 69 74 68 69 6e 20 61 20 70 72 6f 63 65 73 73 20  ithin a process 
0400: 72 61 74 68 65 72 20 74 68 61 6e 20 6a 75 73 74  rather than just
0410: 20 61 6c 6c 0a 20 20 63 6f 6e 6e 65 63 74 69 6f   all.  connectio
0420: 6e 73 20 77 69 74 68 69 6e 20 61 20 74 68 72 65  ns within a thre
0430: 61 64 2e 20 20 54 68 65 20 70 75 72 70 6f 73 65  ad.  The purpose
0440: 20 6f 66 20 74 68 69 73 20 61 72 74 69 63 6c 65   of this article
0450: 0a 20 20 69 73 20 74 6f 20 64 65 73 63 72 69 62  .  is to describ
0460: 65 20 74 68 65 20 63 68 61 6e 67 65 73 20 74 6f  e the changes to
0470: 20 33 2e 35 2e 30 20 69 6e 20 64 65 74 61 69 6c   3.5.0 in detail
0480: 20 73 6f 20 74 68 61 74 20 75 73 65 72 73 0a 20   so that users. 
0490: 20 6f 66 20 70 72 69 6f 72 20 76 65 72 73 69 6f   of prior versio
04a0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 63 61 6e  ns of SQLite can
04b0: 20 6a 75 64 67 65 20 77 68 61 74 2c 20 69 66 20   judge what, if 
04c0: 61 6e 79 2c 20 65 66 66 6f 72 74 20 77 69 6c 6c  any, effort will
04d0: 0a 20 20 62 65 20 72 65 71 75 69 72 65 64 20 74  .  be required t
04e0: 6f 20 75 70 67 72 61 64 65 20 74 6f 20 6e 65 77  o upgrade to new
04f0: 65 72 20 76 65 72 73 69 6f 6e 73 2e 0a 7d 0a 0a  er versions..}..
0500: 48 45 41 44 49 4e 47 20 31 20 7b 4f 76 65 72 76  HEADING 1 {Overv
0510: 69 65 77 20 4f 66 20 43 68 61 6e 67 65 73 7d 0a  iew Of Changes}.
0520: 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 41  .PARAGRAPH {.  A
0530: 20 71 75 69 63 6b 20 65 6e 75 6d 65 72 61 74 69   quick enumerati
0540: 6f 6e 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  on of the change
0550: 73 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  s in SQLite vers
0560: 69 6f 6e 20 33 2e 35 2e 30 0a 20 20 69 73 20 70  ion 3.5.0.  is p
0570: 72 6f 76 69 64 65 20 68 65 72 65 2e 20 20 53 75  rovide here.  Su
0580: 62 73 65 71 75 65 6e 74 20 73 65 63 74 69 6f 6e  bsequent section
0590: 73 20 77 69 6c 6c 20 64 65 73 63 72 69 62 65 20  s will describe 
05a0: 74 68 65 73 65 0a 20 20 63 68 61 6e 67 65 73 20  these.  changes 
05b0: 69 6e 20 6d 6f 72 65 20 64 65 74 61 69 6c 2e 0a  in more detail..
05c0: 7d 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20  }.PARAGRAPH {.  
05d0: 3c 6f 6c 3e 0a 20 20 3c 6c 69 3e 54 68 65 20 4f  <ol>.  <li>The O
05e0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
05f0: 72 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 6c  r has been compl
0600: 65 74 65 6c 79 20 72 65 77 6f 72 6b 65 64 3a 0a  etely reworked:.
0610: 20 20 3c 6f 6c 20 74 79 70 65 3d 22 61 22 3e 0a    <ol type="a">.
0620: 20 20 3c 6c 69 3e 54 68 65 20 75 6e 64 6f 63 75    <li>The undocu
0630: 6d 65 6e 74 65 64 20 3c 62 3e 73 71 6c 69 74 65  mented <b>sqlite
0640: 33 5f 6f 73 5f 73 77 69 74 63 68 28 29 3c 2f 62  3_os_switch()</b
0650: 3e 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 0a  > interface has.
0660: 20 20 20 20 20 20 62 65 65 6e 20 72 65 6d 6f 76        been remov
0670: 65 64 2e 3c 2f 6c 69 3e 0a 20 20 3c 6c 69 3e 54  ed.</li>.  <li>T
0680: 68 65 20 3c 62 3e 53 51 4c 49 54 45 5f 45 4e 41  he <b>SQLITE_ENA
0690: 42 4c 45 5f 52 45 44 45 46 5f 49 4f 3c 2f 62 3e  BLE_REDEF_IO</b>
06a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 66 6c   compile-time fl
06b0: 61 67 20 6e 6f 20 6c 6f 6e 67 65 72 20 66 75 6e  ag no longer fun
06c0: 63 74 69 6f 6e 73 2e 0a 20 20 20 20 20 20 49 2f  ctions..      I/
06d0: 4f 20 70 72 6f 63 65 64 75 72 65 73 20 61 72 65  O procedures are
06e0: 20 6e 6f 77 20 61 6c 77 61 79 73 20 72 65 64 65   now always rede
06f0: 66 69 6e 61 62 6c 65 2e 3c 2f 6c 69 3e 0a 20 20  finable.</li>.  
0700: 3c 6c 69 3e 54 68 72 65 65 20 6e 65 77 20 6f 62  <li>Three new ob
0710: 6a 65 63 74 73 20 61 72 65 20 64 65 66 69 6e 65  jects are define
0720: 64 20 66 6f 72 20 73 70 65 63 69 66 79 69 6e 67  d for specifying
0730: 20 49 2f 4f 20 70 72 6f 63 65 64 75 72 65 73 3a   I/O procedures:
0740: 0a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f  .      [sqlite3_
0750: 76 66 73 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  vfs], [sqlite3_f
0760: 69 6c 65 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  ile], and [sqlit
0770: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 3c  e3_io_methods].<
0780: 2f 6c 69 3e 0a 20 20 3c 6c 69 3e 54 68 72 65 65  /li>.  <li>Three
0790: 20 6e 65 77 20 69 6e 74 65 72 66 61 63 65 73 20   new interfaces 
07a0: 61 72 65 20 75 73 65 64 20 74 6f 20 63 72 65 61  are used to crea
07b0: 74 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 4f  te alternative O
07c0: 53 20 69 6e 74 65 72 66 61 63 65 73 3a 0a 20 20  S interfaces:.  
07d0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73      [sqlite3_vfs
07e0: 5f 72 65 67 69 73 74 65 72 28 29 5d 2c 20 5b 73  _register()], [s
07f0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
0800: 69 73 74 65 72 28 29 5d 2c 20 61 6e 64 0a 20 20  ister()], and.  
0810: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73      [sqlite3_vfs
0820: 5f 66 69 6e 64 28 29 5d 2e 3c 2f 6c 69 3e 0a 20  _find()].</li>. 
0830: 20 3c 6c 69 3e 41 20 6e 65 77 20 69 6e 74 65 72   <li>A new inter
0840: 66 61 63 65 20 68 61 73 20 62 65 65 6e 20 61 64  face has been ad
0850: 64 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  ded to provided 
0860: 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
0870: 6f 6c 20 6f 76 65 72 0a 20 20 20 20 20 20 74 68  ol over.      th
0880: 65 20 63 72 65 61 74 69 6f 6e 20 6f 66 20 6e 65  e creation of ne
0890: 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
08a0: 63 74 69 6f 6e 73 3a 20 5b 73 71 6c 69 74 65 33  ctions: [sqlite3
08b0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 20 20 20  _open_v2()]..   
08c0: 20 20 20 54 68 65 20 6c 65 67 61 63 79 20 69 6e     The legacy in
08d0: 74 65 72 66 61 63 65 73 20 6f 66 20 5b 73 71 6c  terfaces of [sql
08e0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
08f0: 0a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f  .      [sqlite3_
0900: 6f 70 65 6e 31 36 28 29 5d 20 63 6f 6e 74 69 6e  open16()] contin
0910: 75 65 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 73  ue to be fully s
0920: 75 70 70 6f 72 74 65 64 2e 3c 2f 6c 69 3e 0a 20  upported.</li>. 
0930: 20 3c 2f 6f 6c 3e 3c 2f 6c 69 3e 0a 20 20 3c 6c   </ol></li>.  <l
0940: 69 3e 54 68 65 20 6f 70 74 69 6f 6e 61 6c 20 73  i>The optional s
0950: 68 61 72 65 64 20 63 61 63 68 65 20 61 6e 64 20  hared cache and 
0960: 6d 65 6d 6f 72 79 20 6d 61 6e 61 67 65 6d 65 6e  memory managemen
0970: 74 20 66 65 61 74 75 72 65 73 20 74 68 61 74 0a  t features that.
0980: 20 20 20 20 20 20 77 65 72 65 20 69 6e 74 72 6f        were intro
0990: 64 75 63 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  duced in version
09a0: 20 33 2e 33 2e 30 20 63 61 6e 20 6e 6f 77 20 62   3.3.0 can now b
09b0: 65 20 75 73 65 64 20 61 63 72 6f 73 73 20 6d 75  e used across mu
09c0: 6c 74 69 70 6c 65 0a 20 20 20 20 20 20 74 68 72  ltiple.      thr
09d0: 65 61 64 73 20 77 69 74 68 69 6e 20 74 68 65 20  eads within the 
09e0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 46  same process.  F
09f0: 6f 72 6d 65 72 6c 79 2c 20 74 68 65 73 65 20 65  ormerly, these e
0a00: 78 74 65 6e 73 69 6f 6e 73 20 6f 6e 6c 79 0a 20  xtensions only. 
0a10: 20 20 20 20 20 61 70 70 6c 69 65 64 20 74 6f 20       applied to 
0a20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
0a30: 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 77  ions operating w
0a40: 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 74  ithin a single t
0a50: 68 72 65 61 64 2e 0a 20 20 20 3c 6f 6c 20 74 79  hread..   <ol ty
0a60: 70 65 3d 22 61 22 3e 0a 20 20 20 3c 6c 69 3e 54  pe="a">.   <li>T
0a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
0a80: 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
0a90: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6e 6f 77  )] interface now
0aa0: 20 61 70 70 6c 69 65 73 20 74 6f 20 61 6c 6c 0a   applies to all.
0ab0: 20 20 20 20 20 20 20 74 68 72 65 61 64 73 20 77         threads w
0ac0: 69 74 68 69 6e 20 61 20 70 72 6f 63 65 73 73 2c  ithin a process,
0ad0: 20 6e 6f 74 20 74 6f 20 6a 75 73 74 20 74 68 65   not to just the
0ae0: 20 6f 6e 65 20 74 68 72 65 61 64 20 69 6e 20 77   one thread in w
0af0: 68 69 63 68 20 69 74 0a 20 20 20 20 20 20 20 77  hich it.       w
0b00: 61 73 20 72 75 6e 2e 3c 2f 6c 69 3e 0a 20 20 20  as run.</li>.   
0b10: 3c 6c 69 3e 54 68 65 20 5b 73 71 6c 69 74 65 33  <li>The [sqlite3
0b20: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
0b30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6e 6f  ()] interface no
0b40: 77 20 61 70 70 6c 69 65 73 20 74 6f 20 61 6c 6c  w applies to all
0b50: 20 74 68 72 65 61 64 73 0a 20 20 20 20 20 20 20   threads.       
0b60: 77 69 74 68 69 6e 20 61 20 70 72 6f 63 65 73 73  within a process
0b70: 2c 20 6e 6f 74 20 74 6f 20 6a 75 73 74 20 74 68  , not to just th
0b80: 65 20 6f 6e 65 20 74 68 72 65 61 64 20 69 6e 20  e one thread in 
0b90: 77 68 69 63 68 20 69 74 20 77 61 73 20 72 75 6e  which it was run
0ba0: 2e 3c 2f 6c 69 3e 0a 20 20 20 3c 6c 69 3e 54 68  .</li>.   <li>Th
0bb0: 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  e [sqlite3_relea
0bc0: 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74  se_memory()] int
0bd0: 65 72 66 61 63 65 20 77 69 6c 6c 20 6e 6f 77 20  erface will now 
0be0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63  attempt to reduc
0bf0: 65 0a 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d  e.       the mem
0c00: 6f 72 79 20 75 73 61 67 65 73 20 61 63 72 6f 73  ory usages acros
0c10: 73 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  s all database c
0c20: 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 6e 20 61 6c  onnections in al
0c30: 6c 20 74 68 72 65 61 64 73 2c 20 6e 6f 74 0a 20  l threads, not. 
0c40: 20 20 20 20 20 20 6a 75 73 74 20 63 6f 6e 6e 65        just conne
0c50: 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 74 68  ctions in the th
0c60: 72 65 61 64 20 77 68 65 72 65 20 74 68 65 20 69  read where the i
0c70: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
0c80: 65 64 2e 3c 2f 6c 69 3e 0a 20 20 20 3c 6c 69 3e  ed.</li>.   <li>
0c90: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  The [sqlite3_thr
0ca0: 65 61 64 5f 63 6c 65 61 6e 75 70 28 29 5d 20 69  ead_cleanup()] i
0cb0: 6e 74 65 72 66 61 63 65 20 68 61 73 20 62 65 63  nterface has bec
0cc0: 6f 6d 65 20 61 20 6e 6f 2d 6f 70 2e 3c 2f 6c 69  ome a no-op.</li
0cd0: 3e 0a 20 20 20 3c 2f 6f 6c 3e 3c 2f 6c 69 3e 0a  >.   </ol></li>.
0ce0: 20 20 3c 6c 69 3e 52 65 73 74 72 69 63 74 69 6f    <li>Restrictio
0cf0: 6e 73 20 6f 6e 20 74 68 65 20 75 73 65 20 6f 66  ns on the use of
0d00: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
0d10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79  se connection by
0d20: 20 6d 75 6c 74 69 70 6c 65 0a 20 20 20 20 20 20   multiple.      
0d30: 74 68 72 65 61 64 73 20 68 61 76 65 20 62 65 65  threads have bee
0d40: 6e 20 64 72 6f 70 70 65 64 2e 20 20 49 74 20 69  n dropped.  It i
0d50: 73 20 6e 6f 77 20 73 61 66 65 20 66 6f 72 0a 20  s now safe for. 
0d60: 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20 74 68       multiple th
0d70: 72 65 61 64 73 20 74 6f 20 75 73 65 20 74 68 65  reads to use the
0d80: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
0d90: 6f 6e 6e 65 63 74 69 6f 6e 20 61 74 20 74 68 65  onnection at the
0da0: 20 73 61 6d 65 0a 20 20 20 20 20 20 74 69 6d 65   same.      time
0db0: 2e 3c 2f 6c 69 3e 0a 20 20 3c 6c 69 3e 54 68 65  .</li>.  <li>The
0dc0: 72 65 20 69 73 20 6e 6f 77 20 61 20 63 6f 6d 70  re is now a comp
0dd0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
0de0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
0df0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 20 20  pplication to.  
0e00: 20 20 20 20 64 65 66 69 6e 65 20 61 6c 74 65 72      define alter
0e10: 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 2f  native malloc()/
0e20: 66 72 65 65 28 29 20 69 6d 70 6c 65 6d 65 6e 74  free() implement
0e30: 61 74 69 6f 6e 73 20 77 69 74 68 6f 75 74 20 68  ations without h
0e40: 61 76 69 6e 67 0a 20 20 20 20 20 20 74 6f 20 6d  aving.      to m
0e50: 6f 64 69 66 79 20 61 6e 79 20 63 6f 72 65 20 53  odify any core S
0e60: 51 4c 69 74 65 20 63 6f 64 65 2e 3c 2f 6c 69 3e  QLite code.</li>
0e70: 0a 20 20 3c 6c 69 3e 54 68 65 72 65 20 69 73 20  .  <li>There is 
0e80: 6e 6f 77 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69  now a compile-ti
0e90: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 61  me option that a
0ea0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
0eb0: 74 69 6f 6e 20 74 6f 0a 20 20 20 20 20 20 64 65  tion to.      de
0ec0: 66 69 6e 65 20 61 6c 74 65 72 6e 61 74 69 76 65  fine alternative
0ed0: 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
0ee0: 61 74 69 6f 6e 73 20 77 69 74 68 6f 75 74 20 68  ations without h
0ef0: 61 76 69 6e 67 0a 20 20 20 20 20 20 74 6f 20 6d  aving.      to m
0f00: 6f 64 69 66 79 20 61 6e 79 20 63 6f 72 65 20 53  odify any core S
0f10: 51 4c 69 74 65 20 63 6f 64 65 2e 3c 2f 6c 69 3e  QLite code.</li>
0f20: 0a 20 20 3c 2f 6f 6c 3e 0a 7d 0a 50 41 52 41 47  .  </ol>.}.PARAG
0f30: 52 41 50 48 20 7b 0a 20 20 4f 66 20 74 68 65 73  RAPH {.  Of thes
0f40: 65 20 63 68 61 6e 67 65 73 2c 20 6f 6e 6c 79 20  e changes, only 
0f50: 31 61 20 61 6e 64 20 32 61 20 74 68 72 6f 75 67  1a and 2a throug
0f60: 68 20 32 63 20 61 72 65 20 69 6e 63 6f 6d 70 61  h 2c are incompa
0f70: 74 69 62 69 6c 69 74 69 65 73 0a 20 20 69 6e 20  tibilities.  in 
0f80: 61 6e 79 20 66 6f 72 6d 61 6c 20 73 65 6e 73 65  any formal sense
0f90: 2e 0a 20 20 42 75 74 20 75 73 65 72 73 20 77 68  ..  But users wh
0fa0: 6f 20 68 61 76 65 20 70 72 65 76 69 6f 75 73 6c  o have previousl
0fb0: 79 20 6d 61 64 65 20 63 75 73 74 6f 6d 20 6d 6f  y made custom mo
0fc0: 64 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  difications to t
0fd0: 68 65 0a 20 20 53 51 4c 69 74 65 20 73 6f 75 72  he.  SQLite sour
0fe0: 63 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ce (for example 
0ff0: 74 6f 20 61 64 64 20 61 20 63 75 73 74 6f 6d 20  to add a custom 
1000: 4f 53 20 6c 61 79 65 72 20 66 6f 72 20 65 6d 62  OS layer for emb
1010: 65 64 64 65 64 0a 20 20 68 61 72 64 77 61 72 65  edded.  hardware
1020: 29 20 6d 69 67 68 74 20 66 69 6e 64 20 74 68 61  ) might find tha
1030: 74 20 74 68 65 73 65 20 63 68 61 6e 67 65 73 20  t these changes 
1040: 68 61 76 65 20 61 20 6c 61 72 67 65 72 20 69 6d  have a larger im
1050: 70 61 63 74 2e 0a 20 20 4f 6e 20 74 68 65 20 6f  pact..  On the o
1060: 74 68 65 72 20 68 61 6e 64 2c 20 61 6e 20 69 6d  ther hand, an im
1070: 70 6f 72 74 61 6e 74 20 67 6f 61 6c 20 6f 66 20  portant goal of 
1080: 74 68 65 73 65 20 63 68 61 6e 67 65 73 20 69 73  these changes is
1090: 20 74 6f 20 6d 61 6b 65 0a 20 20 69 74 20 6d 75   to make.  it mu
10a0: 63 68 20 65 61 73 69 65 72 20 74 6f 20 63 75 73  ch easier to cus
10b0: 74 6f 6d 69 7a 65 20 53 51 4c 69 74 65 20 66 6f  tomize SQLite fo
10c0: 72 20 75 73 65 20 6f 6e 20 64 69 66 66 65 72 65  r use on differe
10d0: 6e 74 20 6f 70 65 72 61 74 69 6e 67 0a 20 20 73  nt operating.  s
10e0: 79 73 74 65 6d 73 2e 20 0a 7d 0a 0a 48 45 41 44  ystems. .}..HEAD
10f0: 49 4e 47 20 31 20 7b 54 68 65 20 4f 53 20 49 6e  ING 1 {The OS In
1100: 74 65 72 66 61 63 65 20 4c 61 79 65 72 7d 0a 0a  terface Layer}..
1110: 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 49 66  PARAGRAPH {.  If
1120: 20 79 6f 75 72 20 73 79 73 74 65 6d 20 64 65 66   your system def
1130: 69 6e 65 73 20 61 20 63 75 73 74 6f 6d 20 4f 53  ines a custom OS
1140: 20 69 6e 74 65 72 66 61 63 65 20 66 6f 72 20 53   interface for S
1150: 51 4c 69 74 65 20 6f 72 20 69 66 20 79 6f 75 0a  QLite or if you.
1160: 20 20 77 65 72 65 20 75 73 69 6e 67 20 74 68 65    were using the
1170: 20 75 6e 64 6f 63 75 6d 65 6e 74 65 64 20 3c 62   undocumented <b
1180: 3e 73 71 6c 69 74 65 33 5f 6f 73 5f 73 77 69 74  >sqlite3_os_swit
1190: 63 68 28 29 3c 2f 62 3e 0a 20 20 69 6e 74 65 72  ch()</b>.  inter
11a0: 66 61 63 65 2c 20 74 68 65 6e 20 79 6f 75 20 77  face, then you w
11b0: 69 6c 6c 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  ill need to make
11c0: 20 6d 6f 64 69 66 69 63 61 74 69 6f 6e 73 20 69   modifications i
11d0: 6e 20 6f 72 64 65 72 20 74 6f 0a 20 20 75 70 67  n order to.  upg
11e0: 72 61 64 65 20 74 6f 20 53 51 4c 69 74 65 20 76  rade to SQLite v
11f0: 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 20 54  ersion 3.5.0.  T
1200: 68 69 73 20 6d 61 79 20 73 65 65 6d 20 70 61 69  his may seem pai
1210: 6e 66 75 6c 20 61 74 20 66 69 72 73 74 0a 20 20  nful at first.  
1220: 67 6c 61 6e 63 65 2e 20 20 42 75 74 20 61 73 20  glance.  But as 
1230: 79 6f 75 20 6c 6f 6f 6b 20 6d 6f 72 65 20 63 6c  you look more cl
1240: 6f 73 65 6c 79 2c 20 79 6f 75 20 77 69 6c 6c 20  osely, you will 
1250: 70 72 6f 62 61 62 6c 79 20 64 69 73 63 6f 76 65  probably discove
1260: 72 0a 20 20 74 68 61 74 20 79 6f 75 72 20 63 68  r.  that your ch
1270: 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 73  anges are made s
1280: 6d 61 6c 6c 65 72 20 61 6e 64 20 65 61 73 69 65  maller and easie
1290: 72 20 74 6f 20 75 6e 64 65 72 73 74 61 6e 64 20  r to understand 
12a0: 61 6e 64 20 6d 61 6e 61 67 65 0a 20 20 62 79 20  and manage.  by 
12b0: 74 68 65 20 6e 65 77 20 53 51 4c 69 74 65 20 69  the new SQLite i
12c0: 6e 74 65 72 66 61 63 65 2e 20 20 49 74 20 69 73  nterface.  It is
12d0: 20 6c 69 6b 65 6c 79 20 74 68 61 74 20 79 6f 75   likely that you
12e0: 72 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 0a 20  r changes will. 
12f0: 20 6e 6f 77 20 61 6c 73 6f 20 77 6f 72 6b 20 73   now also work s
1300: 65 61 6d 6c 65 73 73 6c 79 20 77 69 74 68 20 74  eamlessly with t
1310: 68 65 20 53 51 4c 69 74 65 20 61 6d 61 6c 67 61  he SQLite amalga
1320: 6d 61 74 69 6f 6e 2e 20 20 59 6f 75 20 77 69 6c  mation.  You wil
1330: 6c 0a 20 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65  l.  no longer ne
1340: 65 64 20 74 6f 20 6d 61 6b 65 20 61 6e 79 20 63  ed to make any c
1350: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
1360: 64 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  de SQLite source
1370: 20 63 6f 64 65 2e 0a 20 20 41 6c 6c 20 6f 66 20   code..  All of 
1380: 79 6f 75 72 20 63 68 61 6e 67 65 73 20 63 61 6e  your changes can
1390: 20 62 65 20 65 66 66 65 63 74 65 64 20 62 79 20   be effected by 
13a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
13b0: 20 61 6e 64 20 79 6f 75 20 63 61 6e 0a 20 20 6c   and you can.  l
13c0: 69 6e 6b 20 61 67 61 69 6e 73 74 20 61 20 73 74  ink against a st
13d0: 61 6e 64 61 72 64 2c 20 75 6e 6d 6f 64 69 66 69  andard, unmodifi
13e0: 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
13f0: 65 20 53 51 4c 69 74 65 20 61 6d 61 6c 67 61 6d  e SQLite amalgam
1400: 61 74 69 6f 6e 2e 0a 20 20 46 75 72 74 68 65 72  ation..  Further
1410: 6d 6f 72 65 2c 20 74 68 65 20 4f 53 20 69 6e 74  more, the OS int
1420: 65 72 66 61 63 65 20 6c 61 79 65 72 2c 20 77 68  erface layer, wh
1430: 69 63 68 20 77 61 73 20 66 6f 72 6d 65 72 6c 79  ich was formerly
1440: 20 75 6e 64 6f 63 75 6d 65 6e 74 65 64 2c 0a 20   undocumented,. 
1450: 20 69 73 20 6e 6f 77 20 61 6e 20 6f 66 66 69 63   is now an offic
1460: 69 61 6c 6c 79 20 73 75 70 70 6f 72 74 20 69 6e  ially support in
1470: 74 65 72 66 61 63 65 20 66 6f 72 20 53 51 4c 69  terface for SQLi
1480: 74 65 2e 20 20 53 6f 20 79 6f 75 20 68 61 76 65  te.  So you have
1490: 0a 20 20 73 6f 6d 65 20 61 73 73 75 72 61 6e 63  .  some assuranc
14a0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
14b0: 20 62 65 20 61 20 6f 6e 65 2d 74 69 6d 65 20 63   be a one-time c
14c0: 68 61 6e 67 65 20 61 6e 64 20 74 68 61 74 20 79  hange and that y
14d0: 6f 75 72 0a 20 20 6e 65 77 20 62 61 63 6b 65 6e  our.  new backen
14e0: 64 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  d will continue 
14f0: 74 6f 20 77 6f 72 6b 20 69 6e 20 66 75 74 75 72  to work in futur
1500: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1510: 4c 69 74 65 2e 0a 7d 0a 0a 48 45 41 44 49 4e 47  Lite..}..HEADING
1520: 20 32 20 7b 54 68 65 20 56 69 72 74 75 61 6c 20   2 {The Virtual 
1530: 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65  File System Obje
1540: 63 74 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b  ct}..PARAGRAPH {
1550: 0a 20 20 54 68 65 20 6e 65 77 20 4f 53 20 69 6e  .  The new OS in
1560: 74 65 72 66 61 63 65 20 66 6f 72 20 53 51 4c 69  terface for SQLi
1570: 74 65 20 69 73 20 62 75 69 6c 74 20 61 72 6f 75  te is built arou
1580: 6e 64 20 61 6e 20 6f 62 6a 65 63 74 20 6e 61 6d  nd an object nam
1590: 65 64 0a 20 20 5b 73 71 6c 69 74 65 33 5f 76 66  ed.  [sqlite3_vf
15a0: 73 5d 2e 20 20 54 68 65 20 22 76 66 73 22 20 73  s].  The "vfs" s
15b0: 74 61 6e 64 73 20 66 6f 72 20 22 56 69 72 74 75  tands for "Virtu
15c0: 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 22 2e  al File System".
15d0: 0a 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  .  The sqlite3_v
15e0: 66 73 20 6f 62 6a 65 63 74 20 69 73 20 62 61 73  fs object is bas
15f0: 69 63 61 6c 6c 79 20 61 20 73 74 72 75 63 74 75  ically a structu
1600: 72 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 70 6f  re containing po
1610: 69 6e 74 65 72 73 0a 20 20 74 6f 20 66 75 6e 63  inters.  to func
1620: 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
1630: 6d 65 6e 74 20 74 68 65 20 70 72 69 6d 69 74 69  ment the primiti
1640: 76 65 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  ve disk I/O oper
1650: 61 74 69 6f 6e 73 20 74 68 61 74 0a 20 20 53 51  ations that.  SQ
1660: 4c 69 74 65 20 6e 65 65 64 73 20 74 6f 20 70 65  Lite needs to pe
1670: 72 66 6f 72 6d 20 69 6e 20 6f 72 64 65 72 20 74  rform in order t
1680: 6f 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65  o read and write
1690: 20 64 61 74 61 62 61 73 65 73 2e 20 20 0a 20 20   databases.  .  
16a0: 49 6e 20 74 68 69 73 20 61 72 74 69 63 6c 65 2c  In this article,
16b0: 20 77 65 20 77 69 6c 6c 20 6f 66 74 65 6e 20 72   we will often r
16c0: 65 66 65 72 20 61 20 73 71 6c 69 74 65 33 5f 76  efer a sqlite3_v
16d0: 66 73 20 6f 62 6a 65 63 74 73 20 61 73 20 61 20  fs objects as a 
16e0: 22 56 46 53 22 2e 0a 7d 0a 0a 50 41 52 41 47 52  "VFS"..}..PARAGR
16f0: 41 50 48 20 7b 0a 20 20 53 51 4c 69 74 65 20 69  APH {.  SQLite i
1700: 73 20 61 62 6c 65 20 74 6f 20 75 73 65 20 6d 75  s able to use mu
1710: 6c 74 69 70 6c 65 20 56 46 53 65 73 20 61 74 20  ltiple VFSes at 
1720: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
1730: 45 61 63 68 0a 20 20 69 6e 64 69 76 69 64 75 61  Each.  individua
1740: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
1750: 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61  ction is associa
1760: 74 65 64 20 77 69 74 68 20 6a 75 73 74 20 6f 6e  ted with just on
1770: 65 20 56 46 53 2e 0a 20 20 42 75 74 20 69 66 20  e VFS..  But if 
1780: 79 6f 75 20 68 61 76 65 20 6d 75 6c 74 69 70 6c  you have multipl
1790: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17a0: 63 74 69 6f 6e 73 2c 20 65 61 63 68 20 63 6f 6e  ctions, each con
17b0: 6e 65 63 74 69 6f 6e 0a 20 20 63 61 6e 20 62 65  nection.  can be
17c0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
17d0: 20 61 20 64 69 66 66 65 72 65 6e 74 20 56 46 53   a different VFS
17e0: 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b  ..}..PARAGRAPH {
17f0: 0a 20 20 54 68 65 72 65 20 69 73 20 61 6c 77 61  .  There is alwa
1800: 79 73 20 61 20 64 65 66 61 75 6c 74 20 56 46 53  ys a default VFS
1810: 2e 0a 20 20 54 68 65 20 6c 65 67 61 63 79 20 69  ..  The legacy i
1820: 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
1830: 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b  e3_open()] and [
1840: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1850: 5d 20 61 6c 77 61 79 73 0a 20 20 75 73 65 20 74  ] always.  use t
1860: 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2e 0a  he default VFS..
1870: 20 20 54 68 65 20 6e 65 77 20 69 6e 74 65 72 66    The new interf
1880: 61 63 65 20 66 6f 72 20 63 72 65 61 74 69 6e 67  ace for creating
1890: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18a0: 74 69 6f 6e 73 2c 0a 20 20 5b 73 71 6c 69 74 65  tions,.  [sqlite
18b0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6c  3_open_v2()], al
18c0: 6c 6f 77 73 20 79 6f 75 20 74 6f 20 73 70 65 63  lows you to spec
18d0: 69 66 79 20 77 68 69 63 68 20 56 46 53 20 79 6f  ify which VFS yo
18e0: 75 20 77 61 6e 74 20 74 6f 0a 20 20 75 73 65 20  u want to.  use 
18f0: 62 79 20 6e 61 6d 65 2e 0a 7d 0a 0a 48 45 41 44  by name..}..HEAD
1900: 49 4e 47 20 33 20 7b 52 65 67 69 73 74 65 72 69  ING 3 {Registeri
1910: 6e 67 20 4e 65 77 20 56 46 53 20 4f 62 6a 65 63  ng New VFS Objec
1920: 74 73 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b  ts}..PARAGRAPH {
1930: 0a 20 20 53 74 61 6e 64 61 72 64 20 62 75 69 6c  .  Standard buil
1940: 64 73 20 6f 66 20 53 51 4c 69 74 65 20 66 6f 72  ds of SQLite for
1950: 20 55 6e 69 78 20 6f 72 20 57 69 6e 64 6f 77 73   Unix or Windows
1960: 20 63 6f 6d 65 20 77 69 74 68 20 61 20 73 69 6e   come with a sin
1970: 67 6c 65 0a 20 20 56 46 53 20 6e 61 6d 65 64 20  gle.  VFS named 
1980: 22 75 6e 69 78 22 20 6f 72 20 22 77 69 6e 33 32  "unix" or "win32
1990: 22 2c 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  ", as appropriat
19a0: 65 2e 20 20 54 68 69 73 20 6f 6e 65 20 56 46 53  e.  This one VFS
19b0: 20 69 73 20 61 6c 73 6f 20 0a 20 20 74 68 65 20   is also .  the 
19c0: 64 65 66 61 75 6c 74 2e 20 20 53 6f 20 69 66 20  default.  So if 
19d0: 79 6f 75 20 61 72 65 20 75 73 69 6e 67 20 74 68  you are using th
19e0: 65 20 6c 65 67 61 63 79 20 6f 70 65 6e 20 66 75  e legacy open fu
19f0: 6e 63 74 69 6f 6e 73 2c 20 65 76 65 72 79 74 68  nctions, everyth
1a00: 69 6e 67 0a 20 20 77 69 6c 6c 20 63 6f 6e 74 69  ing.  will conti
1a10: 6e 75 65 20 74 6f 20 6f 70 65 72 61 74 65 20 61  nue to operate a
1a20: 73 20 69 74 20 68 61 73 20 62 65 66 6f 72 65 2e  s it has before.
1a30: 20 20 54 68 65 20 63 68 61 6e 67 65 20 69 73 20    The change is 
1a40: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
1a50: 69 6f 6e 0a 20 20 6e 6f 77 20 68 61 73 20 74 68  ion.  now has th
1a60: 65 20 66 6c 65 78 69 62 69 6c 69 74 79 20 6f 66  e flexibility of
1a70: 20 61 64 64 69 6e 67 20 6e 65 77 20 56 46 53 20   adding new VFS 
1a80: 6d 6f 64 75 6c 65 73 20 74 6f 20 69 6d 70 6c 65  modules to imple
1a90: 6d 65 6e 74 20 61 0a 20 20 63 75 73 74 6f 6d 69  ment a.  customi
1aa0: 7a 65 64 20 4f 53 20 6c 61 79 65 72 2e 20 20 54  zed OS layer.  T
1ab0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
1ac0: 72 65 67 69 73 74 65 72 28 29 5d 20 41 50 49 20  register()] API 
1ad0: 63 61 6e 20 62 65 20 75 73 65 64 0a 20 20 74 6f  can be used.  to
1ae0: 20 74 65 6c 6c 20 53 51 4c 69 74 65 20 61 62 6f   tell SQLite abo
1af0: 75 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61  ut one or more a
1b00: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1b10: 65 64 20 56 46 53 20 6d 6f 64 75 6c 65 73 3a 0a  ed VFS modules:.
1b20: 7d 0a 0a 43 4f 44 45 20 7b 0a 69 6e 74 20 73 71  }..CODE {.int sq
1b30: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
1b40: 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  er(sqlite3_vfs*,
1b50: 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a   int makeDflt);.
1b60: 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20  }..PARAGRAPH {. 
1b70: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 63 61   Applications ca
1b80: 6e 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 76  n call sqlite3_v
1b90: 66 73 5f 72 65 67 69 73 74 65 72 20 61 74 20 61  fs_register at a
1ba0: 6e 79 20 74 69 6d 65 2c 20 74 68 6f 75 67 68 20  ny time, though 
1bb0: 6f 66 20 63 6f 75 72 73 65 0a 20 20 61 20 56 46  of course.  a VF
1bc0: 53 20 6e 65 65 64 73 20 74 6f 20 62 65 20 72 65  S needs to be re
1bd0: 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 20  gistered before 
1be0: 69 74 20 63 61 6e 20 62 65 20 75 73 65 64 2e 20  it can be used. 
1bf0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1c00: 65 6e 74 0a 20 20 69 73 20 61 20 70 6f 69 6e 74  ent.  is a point
1c10: 65 72 20 74 6f 20 61 20 63 75 73 74 6f 6d 69 7a  er to a customiz
1c20: 65 64 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68  ed VFS object th
1c30: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
1c40: 6f 6e 20 68 61 73 20 70 72 65 70 61 72 65 64 2e  on has prepared.
1c50: 0a 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
1c60: 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 20 74  gument is true t
1c70: 6f 20 6d 61 6b 65 20 74 68 65 20 6e 65 77 20 56  o make the new V
1c80: 46 53 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  FS the default V
1c90: 46 53 20 73 6f 20 74 68 61 74 0a 20 20 69 74 20  FS so that.  it 
1ca0: 77 69 6c 6c 20 62 65 20 75 73 65 64 20 62 79 20  will be used by 
1cb0: 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
1cc0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
1cd0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1ce0: 29 5d 20 41 50 49 73 2e 0a 20 20 49 66 20 74 68  )] APIs..  If th
1cf0: 65 20 6e 65 77 20 56 46 53 20 69 73 20 6e 6f 74  e new VFS is not
1d00: 20 74 68 65 20 64 65 66 61 75 6c 74 2c 20 74 68   the default, th
1d10: 65 6e 20 79 6f 75 20 77 69 6c 6c 20 70 72 6f 62  en you will prob
1d20: 61 62 6c 79 20 68 61 76 65 20 74 6f 20 75 73 65  ably have to use
1d30: 0a 20 20 74 68 65 20 6e 65 77 20 5b 73 71 6c 69  .  the new [sqli
1d40: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 41  te3_open_v2()] A
1d50: 50 49 20 74 6f 20 75 73 65 20 69 74 2e 20 20 4e  PI to use it.  N
1d60: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
1d70: 61 74 20 69 66 0a 20 20 61 20 6e 65 77 20 56 46  at if.  a new VF
1d80: 53 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 56 46  S is the only VF
1d90: 53 20 6b 6e 6f 77 6e 20 74 6f 20 53 51 4c 69 74  S known to SQLit
1da0: 65 20 28 69 66 20 53 51 4c 69 74 65 20 77 61 73  e (if SQLite was
1db0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 6f 75   compiled withou
1dc0: 74 0a 20 20 69 74 73 20 75 73 75 61 6c 20 64 65  t.  its usual de
1dd0: 66 61 75 6c 74 20 56 46 53 20 6f 72 20 69 66 20  fault VFS or if 
1de0: 74 68 65 20 70 72 65 63 6f 6d 70 69 6c 65 64 20  the precompiled 
1df0: 64 65 66 61 75 6c 74 20 56 46 53 20 77 61 73 20  default VFS was 
1e00: 72 65 6d 6f 76 65 64 0a 20 20 75 73 69 6e 67 20  removed.  using 
1e10: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
1e20: 65 67 69 73 74 65 72 28 29 5d 29 20 74 68 65 6e  egister()]) then
1e30: 20 74 68 65 20 6e 65 77 20 56 46 53 20 61 75 74   the new VFS aut
1e40: 6f 6d 61 74 69 63 20 62 65 63 6f 6d 65 73 20 74  omatic becomes t
1e50: 68 65 0a 20 20 64 65 66 61 75 6c 74 20 56 46 53  he.  default VFS
1e60: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
1e70: 68 65 20 6d 61 6b 65 44 66 6c 74 20 61 72 67 75  he makeDflt argu
1e80: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1e90: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
1ea0: 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b  ..}..PARAGRAPH {
1eb0: 0a 20 20 53 74 61 6e 64 61 72 64 20 62 75 69 6c  .  Standard buil
1ec0: 64 73 20 69 6e 63 6c 75 64 65 20 74 68 65 20 64  ds include the d
1ed0: 65 66 61 75 6c 74 20 22 75 6e 69 78 22 20 6f 72  efault "unix" or
1ee0: 20 22 77 69 6e 33 32 22 20 56 46 53 65 73 2e 0a   "win32" VFSes..
1ef0: 20 20 42 75 74 20 69 66 20 79 6f 75 20 75 73 65    But if you use
1f00: 20 74 68 65 20 2d 44 4f 53 5f 4f 54 48 45 52 3d   the -DOS_OTHER=
1f10: 31 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  1 compile-time o
1f20: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69  ption, then SQLi
1f30: 74 65 20 69 73 0a 20 20 62 75 69 6c 74 20 77 69  te is.  built wi
1f40: 74 68 6f 75 74 20 61 20 64 65 66 61 75 6c 74 20  thout a default 
1f50: 56 46 53 2e 20 20 49 6e 20 74 68 61 74 20 63 61  VFS.  In that ca
1f60: 73 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  se, the applicat
1f70: 69 6f 6e 20 6d 75 73 74 0a 20 20 72 65 67 69 73  ion must.  regis
1f80: 74 65 72 20 61 74 20 6c 65 61 73 74 20 6f 6e 65  ter at least one
1f90: 20 56 46 53 20 70 72 69 6f 72 20 74 6f 20 63 61   VFS prior to ca
1fa0: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  lling [sqlite3_o
1fb0: 70 65 6e 28 29 5d 2e 0a 20 20 54 68 69 73 20 69  pen()]..  This i
1fc0: 73 20 74 68 65 20 61 70 70 72 6f 61 63 68 20 74  s the approach t
1fd0: 68 61 74 20 65 6d 62 65 64 64 65 64 20 61 70 70  hat embedded app
1fe0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
1ff0: 20 75 73 65 2e 0a 20 20 52 61 74 68 65 72 20 74   use..  Rather t
2000: 68 61 6e 20 6d 6f 64 69 66 79 69 6e 67 20 74 68  han modifying th
2010: 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  e SQLite source 
2020: 74 6f 20 69 6e 73 65 72 74 20 61 6e 20 61 6c 74  to insert an alt
2030: 65 72 6e 61 74 69 76 65 0a 20 20 4f 53 20 6c 61  ernative.  OS la
2040: 79 65 72 20 61 73 20 77 61 73 20 64 6f 6e 65 20  yer as was done 
2050: 69 6e 20 70 72 69 6f 72 20 72 65 6c 65 61 73 65  in prior release
2060: 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 6e 73  s of SQLite, ins
2070: 74 65 61 64 20 63 6f 6d 70 69 6c 65 0a 20 20 61  tead compile.  a
2080: 6e 20 75 6e 6d 6f 64 69 66 69 65 64 20 53 51 4c  n unmodified SQL
2090: 69 74 65 20 73 6f 75 72 63 65 20 66 69 6c 65 20  ite source file 
20a0: 28 70 72 65 66 65 72 61 62 6c 79 20 74 68 65 20  (preferably the 
20b0: 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 29 0a 20 20  amalgamation).  
20c0: 77 69 74 68 20 74 68 65 20 2d 44 4f 53 5f 4f 54  with the -DOS_OT
20d0: 48 45 52 3d 31 20 6f 70 74 69 6f 6e 2c 20 74 68  HER=1 option, th
20e0: 65 6e 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  en invoke [sqlit
20f0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
2100: 29 5d 0a 20 20 74 6f 20 64 65 66 69 6e 65 20 74  )].  to define t
2110: 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
2120: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 66  the underlying f
2130: 69 6c 65 73 79 73 74 65 6d 20 70 72 69 6f 72 20  ilesystem prior 
2140: 74 6f 0a 20 20 63 72 65 61 74 69 6e 67 20 61 6e  to.  creating an
2150: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
2160: 63 74 69 6f 6e 73 2e 0a 7d 0a 0a 48 45 41 44 49  ctions..}..HEADI
2170: 4e 47 20 33 20 7b 41 64 64 69 74 69 6f 6e 61 6c  NG 3 {Additional
2180: 20 43 6f 6e 74 72 6f 6c 20 4f 76 65 72 20 56 46   Control Over VF
2190: 53 20 4f 62 6a 65 63 74 73 7d 0a 0a 50 41 52 41  S Objects}..PARA
21a0: 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20 5b 73  GRAPH {.  The [s
21b0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
21c0: 69 73 74 65 72 28 29 5d 20 41 50 49 20 69 73 20  ister()] API is 
21d0: 75 73 65 64 20 74 6f 20 72 65 6d 6f 76 65 20 61  used to remove a
21e0: 6e 20 65 78 69 73 74 69 6e 67 0a 20 20 56 46 53  n existing.  VFS
21f0: 20 66 72 6f 6d 20 74 68 65 20 73 79 73 74 65 6d   from the system
2200: 2e 0a 7d 0a 0a 43 4f 44 45 20 7b 0a 69 6e 74 20  ..}..CODE {.int 
2210: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
2220: 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
2230: 66 73 2a 29 3b 0a 7d 0a 0a 50 41 52 41 47 52 41  fs*);.}..PARAGRA
2240: 50 48 20 7b 0a 20 20 54 68 65 20 5b 73 71 6c 69  PH {.  The [sqli
2250: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
2260: 41 50 49 20 69 73 20 75 73 65 64 20 74 6f 20 6c  API is used to l
2270: 6f 63 61 74 65 20 61 20 70 61 72 74 69 63 75 6c  ocate a particul
2280: 61 72 20 56 46 53 0a 20 20 62 79 20 6e 61 6d 65  ar VFS.  by name
2290: 2e 20 20 49 74 73 20 70 72 6f 74 6f 74 79 70 65  .  Its prototype
22a0: 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
22b0: 7d 0a 0a 43 4f 44 45 20 7b 0a 73 71 6c 69 74 65  }..CODE {.sqlite
22c0: 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
22d0: 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
22e0: 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 7d  ar *zVfsName);.}
22f0: 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20  ..PARAGRAPH {.  
2300: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
2310: 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  the symbolic nam
2320: 65 20 66 6f 72 20 74 68 65 20 64 65 73 69 72 65  e for the desire
2330: 64 20 56 46 53 2e 20 20 49 66 20 74 68 65 0a 20  d VFS.  If the. 
2340: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 4e   argument is a N
2350: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2360: 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  n the default VF
2370: 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 20  S is returned.. 
2380: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
2390: 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
23a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
23b0: 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
23c0: 0a 20 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  .  implements th
23d0: 65 20 56 46 53 2e 20 20 4f 72 20 69 74 20 72 65  e VFS.  Or it re
23e0: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
23f0: 6e 74 65 72 20 69 66 20 6e 6f 20 6f 62 6a 65 63  nter if no objec
2400: 74 0a 20 20 63 6f 75 6c 64 20 62 65 20 66 6f 75  t.  could be fou
2410: 6e 64 20 74 68 61 74 20 6d 61 74 63 68 65 64 20  nd that matched 
2420: 74 68 65 20 73 65 61 72 63 68 20 63 72 69 74 65  the search crite
2430: 72 69 61 2e 0a 7d 0a 0a 48 45 41 44 49 4e 47 20  ria..}..HEADING 
2440: 33 20 7b 4d 6f 64 69 66 69 63 61 74 69 6f 6e 73  3 {Modifications
2450: 20 4f 66 20 45 78 69 73 74 69 6e 67 20 56 46 53   Of Existing VFS
2460: 65 73 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b  es}..PARAGRAPH {
2470: 0a 20 20 4f 6e 63 65 20 61 20 56 46 53 20 68 61  .  Once a VFS ha
2480: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
2490: 64 2c 20 69 74 20 73 68 6f 75 6c 64 20 6e 65 76  d, it should nev
24a0: 65 72 20 62 65 20 6d 6f 64 69 66 69 65 64 2e 20  er be modified. 
24b0: 20 49 66 0a 20 20 61 20 63 68 61 6e 67 65 20 69   If.  a change i
24c0: 6e 20 62 65 68 61 76 69 6f 72 20 69 73 20 72 65  n behavior is re
24d0: 71 75 69 72 65 64 2c 20 61 20 6e 65 77 20 56 46  quired, a new VF
24e0: 53 20 73 68 6f 75 6c 64 20 62 65 20 72 65 67 69  S should be regi
24f0: 73 74 65 72 65 64 2e 0a 20 20 54 68 65 20 61 70  stered..  The ap
2500: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 75 6c 64 2c  plication could,
2510: 20 70 65 72 68 61 70 73 2c 20 75 73 65 20 5b 73   perhaps, use [s
2520: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
2530: 29 5d 20 74 6f 20 6c 6f 63 61 74 65 0a 20 20 74  )] to locate.  t
2540: 68 65 20 6f 6c 64 20 56 46 53 2c 20 6d 61 6b 65  he old VFS, make
2550: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f   a copy of the o
2560: 6c 64 20 56 46 53 20 69 6e 74 6f 20 61 20 6e 65  ld VFS into a ne
2570: 77 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 0a  w [sqlite3_vfs].
2580: 20 20 6f 62 6a 65 63 74 2c 20 6d 61 6b 65 20 74    object, make t
2590: 68 65 20 64 65 73 69 72 65 64 20 6d 6f 64 69 66  he desired modif
25a0: 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  ications to the 
25b0: 6e 65 77 20 56 46 53 2c 20 75 6e 72 65 67 69 73  new VFS, unregis
25c0: 74 65 72 0a 20 20 74 68 65 20 6f 6c 64 20 56 46  ter.  the old VF
25d0: 53 2c 20 74 68 65 20 72 65 67 69 73 74 65 72 20  S, the register 
25e0: 74 68 65 20 6e 65 77 20 56 46 53 20 69 6e 20 69  the new VFS in i
25f0: 74 73 20 70 6c 61 63 65 2e 20 20 45 78 69 73 74  ts place.  Exist
2600: 69 6e 67 0a 20 20 64 61 74 61 62 61 73 65 20 63  ing.  database c
2610: 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 6f 75 6c 64  onnections would
2620: 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 75 73 65   continue to use
2630: 20 74 68 65 20 6f 6c 64 20 56 46 53 20 65 76 65   the old VFS eve
2640: 6e 20 61 66 74 65 72 0a 20 20 69 74 20 69 73 20  n after.  it is 
2650: 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 62 75  unregistered, bu
2660: 74 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  t new database c
2670: 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 6f 75 6c 64  onnections would
2680: 20 75 73 65 20 74 68 65 0a 20 20 6e 65 77 20 56   use the.  new V
2690: 46 53 2e 0a 7d 20 20 0a 0a 48 45 41 44 49 4e 47  FS..}  ..HEADING
26a0: 20 33 20 7b 54 68 65 20 56 46 53 20 4f 62 6a 65   3 {The VFS Obje
26b0: 63 74 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b  ct}..PARAGRAPH {
26c0: 0a 20 20 41 20 56 46 53 20 6f 62 6a 65 63 74 20  .  A VFS object 
26d0: 69 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  is an instance o
26e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
26f0: 73 74 72 75 63 74 75 72 65 3a 0a 7d 0a 0a 43 4f  structure:.}..CO
2700: 44 45 20 7b 0a 74 79 70 65 64 65 66 20 73 74 72  DE {.typedef str
2710: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
2720: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72  sqlite3_vfs;.str
2730: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
2740: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
2750: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
2760: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
2770: 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e  n number */.  in
2780: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
2790: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
27a0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
27b0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
27c0: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
27d0: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
27e0: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
27f0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
2800: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
2810: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
2820: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
2830: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2840: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
2850: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
2860: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
2870: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
2880: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
2890: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
28a0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
28b0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
28c0: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
28d0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
28e0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
28f0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
2900: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
2910: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
2920: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
2930: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
2940: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2950: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
2960: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
2970: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
2980: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2990: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  me, int flags);.
29a0: 20 20 69 6e 74 20 28 2a 78 47 65 74 54 65 6d 70    int (*xGetTemp
29b0: 4e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Name)(sqlite3_vf
29c0: 73 2a 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  s*, char *zOut);
29d0: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
29e0: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
29f0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
2a00: 20 2a 7a 4e 61 6d 65 2c 20 63 68 61 72 20 2a 7a   *zName, char *z
2a10: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
2a20: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
2a30: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
2a40: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
2a50: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
2a60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
2a70: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
2a80: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
2a90: 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c  d *(*xDlSym)(sql
2aa0: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
2ab0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
2ac0: 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a  mbol);.  void (*
2ad0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
2ae0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
2af0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
2b00: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
2b10: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
2b20: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
2b30: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
2b40: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
2b50: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
2b60: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
2b70: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
2b80: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4e  double*);.  /* N
2b90: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
2ba0: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
2bb0: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
2bc0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
2bd0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
2be0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
2bf0: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a  his happens. */.
2c00: 7d 3b 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20  };.}..PARAGRAPH 
2c10: 7b 0a 20 20 54 6f 20 63 72 65 61 74 65 20 61 20  {.  To create a 
2c20: 6e 65 77 20 56 46 53 2c 20 61 6e 20 61 70 70 6c  new VFS, an appl
2c30: 69 63 61 74 69 6f 6e 20 66 69 6c 6c 73 20 69 6e  ication fills in
2c40: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
2c50: 74 68 69 73 0a 20 20 73 74 72 75 63 74 75 72 65  this.  structure
2c60: 20 77 69 74 68 20 61 70 70 72 6f 70 72 69 61 74   with appropriat
2c70: 65 20 76 61 6c 75 65 73 20 61 6e 64 20 74 68 65  e values and the
2c80: 6e 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  n calls [sqlite3
2c90: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
2ca0: 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b  ..}..PARAGRAPH {
2cb0: 0a 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  .  The iVersion 
2cc0: 66 69 65 6c 64 20 6f 66 20 5b 73 71 6c 69 74 65  field of [sqlite
2cd0: 33 5f 76 66 73 5d 20 73 68 6f 75 6c 64 20 62 65  3_vfs] should be
2ce0: 20 31 20 66 6f 72 20 53 51 4c 69 74 65 20 76 65   1 for SQLite ve
2cf0: 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 20 20 54  rsion 3.5.0..  T
2d00: 68 69 73 20 6e 75 6d 62 65 72 20 6d 61 79 20 69  his number may i
2d10: 6e 63 72 65 61 73 65 20 69 6e 20 66 75 74 75 72  ncrease in futur
2d20: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
2d30: 4c 69 74 65 20 69 66 20 77 65 20 68 61 76 65 20  Lite if we have 
2d40: 74 6f 0a 20 20 6d 6f 64 69 66 79 20 74 68 65 20  to.  modify the 
2d50: 56 46 53 20 6f 62 6a 65 63 74 20 69 6e 20 73 6f  VFS object in so
2d60: 6d 65 20 77 61 79 2e 20 20 57 65 20 68 6f 70 65  me way.  We hope
2d70: 20 74 68 61 74 20 74 68 69 73 20 6e 65 76 65 72   that this never
2d80: 20 68 61 70 70 65 6e 73 2c 0a 20 20 62 75 74 20   happens,.  but 
2d90: 74 68 65 20 70 72 6f 76 69 73 69 6f 6e 20 69 73  the provision is
2da0: 20 6d 61 64 65 20 69 6e 20 63 61 73 65 20 69 74   made in case it
2db0: 20 64 6f 65 73 2e 0a 7d 0a 0a 50 41 52 41 47 52   does..}..PARAGR
2dc0: 41 50 48 20 7b 0a 20 20 54 68 65 20 73 7a 4f 73  APH {.  The szOs
2dd0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
2de0: 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
2df0: 6f 66 20 74 68 65 20 73 74 72 75 63 74 75 72 65  of the structure
2e00: 20 74 68 61 74 20 64 65 66 69 6e 65 73 0a 20 20   that defines.  
2e10: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 3a 20 74 68  an open file: th
2e20: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
2e30: 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
2e40: 62 6a 65 63 74 20 77 69 6c 6c 20 62 65 20 64 65  bject will be de
2e50: 73 63 72 69 62 65 64 0a 20 20 6d 6f 72 65 20 66  scribed.  more f
2e60: 75 6c 6c 79 20 62 65 6c 6f 77 2e 20 20 54 68 65  ully below.  The
2e70: 20 70 6f 69 6e 74 20 68 65 72 65 20 69 73 20 74   point here is t
2e80: 68 61 74 20 65 61 63 68 20 56 46 53 20 69 6d 70  hat each VFS imp
2e90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 0a  lementation can.
2ea0: 20 20 64 65 66 69 6e 65 20 69 74 73 20 6f 77 6e    define its own
2eb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
2ec0: 6f 62 6a 65 63 74 20 63 6f 6e 74 61 69 6e 69 6e  object containin
2ed0: 67 20 77 68 61 74 65 76 65 72 20 69 6e 66 6f 72  g whatever infor
2ee0: 6d 61 74 69 6f 6e 0a 20 20 74 68 65 20 56 46 53  mation.  the VFS
2ef0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f00: 6e 65 65 64 73 20 74 6f 20 73 74 6f 72 65 20 61  needs to store a
2f10: 62 6f 75 74 20 61 6e 20 6f 70 65 6e 20 66 69 6c  bout an open fil
2f20: 65 2e 20 20 53 51 4c 69 74 65 20 6e 65 65 64 73  e.  SQLite needs
2f30: 0a 20 20 74 6f 20 6b 6e 6f 77 20 68 6f 77 20 62  .  to know how b
2f40: 69 67 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  ig this object i
2f50: 73 2c 20 68 6f 77 65 76 65 72 2c 20 69 6e 20 6f  s, however, in o
2f60: 72 64 65 72 20 74 6f 20 70 72 65 61 6c 6c 6f 63  rder to prealloc
2f70: 61 74 65 20 65 6e 6f 75 67 68 0a 20 20 73 70 61  ate enough.  spa
2f80: 63 65 20 74 6f 20 68 6f 6c 64 20 69 74 2e 0a 7d  ce to hold it..}
2f90: 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20  ..PARAGRAPH {.  
2fa0: 54 68 65 20 6d 78 50 61 74 68 6e 61 6d 65 20 66  The mxPathname f
2fb0: 69 65 6c 64 20 69 73 20 74 68 65 20 6d 61 78 69  ield is the maxi
2fc0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 20  mum length of a 
2fd0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 74 68  file pathname th
2fe0: 61 74 0a 20 20 74 68 69 73 20 56 46 53 20 63 61  at.  this VFS ca
2ff0: 6e 20 75 73 65 2e 20 20 53 51 4c 69 74 65 20 73  n use.  SQLite s
3000: 6f 6d 65 74 69 6d 65 73 20 68 61 73 20 74 6f 20  ometimes has to 
3010: 70 72 65 61 6c 6c 6f 63 61 74 65 20 62 75 66 66  preallocate buff
3020: 65 72 73 20 6f 66 0a 20 20 74 68 69 73 20 73 69  ers of.  this si
3030: 7a 65 2c 20 73 6f 20 69 74 20 73 68 6f 75 6c 64  ze, so it should
3040: 20 62 65 20 61 73 20 73 6d 61 6c 6c 20 61 73 20   be as small as 
3050: 72 65 61 73 6f 6e 61 62 6c 79 20 70 6f 73 73 69  reasonably possi
3060: 62 6c 65 2e 20 20 53 6f 6d 65 0a 20 20 66 69 6c  ble.  Some.  fil
3070: 65 73 79 73 74 65 6d 73 20 70 65 72 6d 69 74 20  esystems permit 
3080: 68 75 67 65 20 70 61 74 68 6e 61 6d 65 73 2c 20  huge pathnames, 
3090: 62 75 74 20 69 6e 20 70 72 61 63 74 69 63 65 20  but in practice 
30a0: 70 61 74 68 6e 61 6d 65 73 20 72 61 72 65 6c 79  pathnames rarely
30b0: 0a 20 20 65 78 74 65 6e 64 20 62 65 79 6f 6e 64  .  extend beyond
30c0: 20 31 30 30 20 62 79 74 65 73 20 6f 72 20 73 6f   100 bytes or so
30d0: 2e 20 20 59 6f 75 20 64 6f 20 6e 6f 74 20 68 61  .  You do not ha
30e0: 76 65 20 74 6f 20 70 75 74 20 74 68 65 20 6c 6f  ve to put the lo
30f0: 6e 67 65 73 74 0a 20 20 70 61 74 68 6e 61 6d 65  ngest.  pathname
3100: 20 74 68 61 74 20 74 68 65 20 75 6e 64 65 72 6c   that the underl
3110: 79 69 6e 67 20 66 69 6c 65 73 79 73 74 65 6d 20  ying filesystem 
3120: 63 61 6e 20 68 61 6e 64 6c 65 20 68 65 72 65 2e  can handle here.
3130: 20 20 59 6f 75 20 6f 6e 6c 79 0a 20 20 68 61 76    You only.  hav
3140: 65 20 74 6f 20 70 75 74 20 74 68 65 20 6c 6f 6e  e to put the lon
3150: 67 65 73 74 20 70 61 74 68 6e 61 6d 65 20 74 68  gest pathname th
3160: 61 74 20 79 6f 75 20 77 61 6e 74 20 53 51 4c 69  at you want SQLi
3170: 74 65 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  te to be able to
3180: 0a 20 20 68 61 6e 64 6c 65 2e 20 20 41 20 66 65  .  handle.  A fe
3190: 77 20 68 75 6e 64 72 65 64 20 69 73 20 61 20 67  w hundred is a g
31a0: 6f 6f 64 20 76 61 6c 75 65 20 69 6e 20 6d 6f 73  ood value in mos
31b0: 74 20 63 61 73 65 73 2e 0a 7d 0a 0a 50 41 52 41  t cases..}..PARA
31c0: 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20 70 4e  GRAPH {.  The pN
31d0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 75 73 65  ext field is use
31e0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
31f0: 53 51 4c 69 74 65 2e 20 20 53 70 65 63 69 66 69  SQLite.  Specifi
3200: 63 61 6c 6c 79 2c 20 53 51 4c 69 74 65 0a 20 20  cally, SQLite.  
3210: 75 73 65 73 20 74 68 69 73 20 66 69 65 6c 64 20  uses this field 
3220: 74 6f 20 66 6f 72 6d 20 61 20 6c 69 6e 6b 65 64  to form a linked
3230: 20 6c 69 73 74 20 6f 66 20 72 65 67 69 73 74 65   list of registe
3240: 72 65 64 20 56 46 53 65 73 2e 0a 7d 0a 0a 50 41  red VFSes..}..PA
3250: 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20  RAGRAPH {.  The 
3260: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 69 73 20 74  zName field is t
3270: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
3280: 20 6f 66 20 74 68 65 20 56 46 53 2e 20 20 54 68   of the VFS.  Th
3290: 69 73 20 69 73 20 74 68 65 20 6e 61 6d 65 20 0a  is is the name .
32a0: 20 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69    that the [sqli
32b0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
32c0: 63 6f 6d 70 61 72 65 73 20 61 67 61 69 6e 73 74  compares against
32d0: 20 77 68 65 6e 20 69 74 20 69 73 20 6c 6f 6f 6b   when it is look
32e0: 69 6e 67 20 66 6f 72 0a 20 20 61 20 56 46 53 2e  ing for.  a VFS.
32f0: 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a  .}..PARAGRAPH {.
3300: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
3310: 6f 69 6e 74 65 72 20 69 73 20 75 6e 75 73 65 64  ointer is unused
3320: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
3330: 6f 72 65 2e 20 20 54 68 65 20 70 6f 69 6e 74 65  ore.  The pointe
3340: 72 20 69 73 0a 20 20 61 76 61 69 6c 61 62 6c 65  r is.  available
3350: 20 74 6f 20 73 74 6f 72 65 20 61 75 78 69 6c 69   to store auxili
3360: 61 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ary information 
3370: 74 68 61 74 20 61 20 56 46 53 20 69 6e 66 6f 72  that a VFS infor
3380: 6d 61 74 69 6f 6e 20 6d 69 67 68 74 0a 20 20 77  mation might.  w
3390: 61 6e 74 20 74 6f 20 63 61 72 72 79 20 61 72 6f  ant to carry aro
33a0: 75 6e 64 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50  und..}..PARAGRAP
33b0: 48 20 7b 0a 20 20 54 68 65 20 72 65 6d 61 69 6e  H {.  The remain
33c0: 69 6e 67 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ing fields of th
33d0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
33e0: 6f 62 6a 65 63 74 20 61 6c 6c 20 73 74 6f 72 65  object all store
33f0: 20 70 6f 69 6e 74 65 72 0a 20 20 74 6f 20 66 75   pointer.  to fu
3400: 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
3410: 6c 65 6d 65 6e 74 20 70 72 69 6d 69 74 69 76 65  lement primitive
3420: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 20 57 65   operations.  We
3430: 20 63 61 6c 6c 20 74 68 65 73 65 0a 20 20 22 6d   call these.  "m
3440: 65 74 68 6f 64 73 22 2e 20 20 54 68 65 20 66 69  ethods".  The fi
3450: 72 73 74 20 6d 65 74 68 6f 64 73 2c 20 78 4f 70  rst methods, xOp
3460: 65 6e 2c 20 69 73 20 75 73 65 64 20 74 6f 20 6f  en, is used to o
3470: 70 65 6e 20 66 69 6c 65 73 20 6f 6e 0a 20 20 74  pen files on.  t
3480: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 74  he underlying st
3490: 6f 72 61 67 65 20 6d 65 64 69 61 2e 20 20 54 68  orage media.  Th
34a0: 65 20 72 65 73 75 6c 74 20 69 73 20 61 6e 20 5b  e result is an [
34b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 20 20  sqlite3_file].  
34c0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 72 65 20 61  object.  There a
34d0: 72 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65  re additional me
34e0: 74 68 6f 64 73 2c 20 64 65 66 69 6e 65 64 20 62  thods, defined b
34f0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
3500: 69 6c 65 5d 0a 20 20 6f 62 6a 65 63 74 20 69 74  ile].  object it
3510: 73 65 6c 66 20 74 68 61 74 20 61 72 65 20 75 73  self that are us
3520: 65 64 20 74 6f 20 72 65 61 64 20 61 6e 64 20 77  ed to read and w
3530: 72 69 74 65 20 61 6e 64 20 63 6c 6f 73 65 20 74  rite and close t
3540: 68 65 20 66 69 6c 65 2e 0a 20 20 54 68 65 20 61  he file..  The a
3550: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
3560: 73 20 61 72 65 20 64 65 74 61 69 6c 65 64 20 62  s are detailed b
3570: 65 6c 6f 77 2e 20 20 54 68 65 20 66 69 6c 65 6e  elow.  The filen
3580: 61 6d 65 20 69 73 20 69 6e 20 55 54 46 2d 38 2e  ame is in UTF-8.
3590: 0a 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  .  SQLite will g
35a0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
35b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73 74 72 69  e zFilename stri
35c0: 6e 67 20 70 61 73 73 65 64 20 74 6f 0a 20 20 78  ng passed to.  x
35d0: 4f 70 65 6e 28 29 20 69 73 20 61 20 66 75 6c 6c  Open() is a full
35e0: 20 70 61 74 68 6e 61 6d 65 20 61 73 20 67 65 6e   pathname as gen
35f0: 65 72 61 74 65 64 20 62 79 20 78 46 75 6c 6c 50  erated by xFullP
3600: 61 74 68 6e 61 6d 65 28 29 20 61 6e 64 0a 20 20  athname() and.  
3610: 74 68 61 74 20 74 68 65 20 73 74 72 69 6e 67 20  that the string 
3620: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
3630: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
3640: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 20 20  l xClose() is.  
3650: 63 61 6c 6c 65 64 2e 20 20 53 6f 20 74 68 65 20  called.  So the 
3660: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
3670: 61 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  an store a point
3680: 65 72 20 74 6f 20 74 68 65 0a 20 20 20 66 69 6c  er to the.   fil
3690: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
36a0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
36b0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
36c0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 20 20 20 54  ome reason..   T
36d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
36e0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 73 20  t to xOpen() is 
36f0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6c  a copy of the fl
3700: 61 67 73 20 61 72 67 75 6d 65 6e 74 0a 20 20 20  ags argument.   
3710: 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
3720: 76 32 28 29 2e 20 20 49 66 20 73 71 6c 69 74 65  v2().  If sqlite
3730: 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
3740: 74 65 33 5f 6f 70 65 6e 31 36 28 29 0a 20 20 20  te3_open16().   
3750: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
3760: 61 67 73 20 69 73 20 5b 53 51 4c 49 54 45 5f 4f  ags is [SQLITE_O
3770: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
3780: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
3790: 45 41 54 45 5d 2e 0a 20 20 20 49 66 20 78 4f 70  EATE]..   If xOp
37a0: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
37b0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
37c0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
37d0: 61 67 73 20 74 6f 0a 20 20 20 69 6e 63 6c 75 64  ags to.   includ
37e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
37f0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
3800: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
3810: 61 67 73 20 6d 61 79 20 62 65 0a 20 20 20 73 65  ags may be.   se
3820: 74 2e 0a 20 20 20 53 51 4c 69 74 65 20 77 69 6c  t..   SQLite wil
3830: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
3840: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
3850: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
3860: 65 6e 28 29 0a 20 20 20 63 61 6c 6c 2c 20 64 65  en().   call, de
3870: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
3880: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
3890: 65 64 3a 0a 20 20 20 3c 75 6c 3e 0a 20 20 20 3c  ed:.   <ul>.   <
38a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
38b0: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 20 20 20 3c 6c  N_MAIN_DB].   <l
38c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
38d0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 20  _MAIN_JOURNAL]. 
38e0: 20 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f    <li>  [SQLITE_
38f0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 20 20  OPEN_TEMP_DB].  
3900: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
3910: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
3920: 5d 0a 20 20 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].   <li>  [SQLI
3930: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
3940: 54 5f 44 42 5d 0a 20 20 20 3c 6c 69 3e 20 20 5b  T_DB].   <li>  [
3950: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
3960: 4f 55 52 4e 41 4c 5d 0a 20 20 20 3c 6c 69 3e 20  OURNAL].   <li> 
3970: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
3980: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 20 20  STER_JOURNAL].  
3990: 20 3c 2f 75 6c 3e 0a 20 20 20 54 68 65 20 66 69   </ul>.   The fi
39a0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
39b0: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
39c0: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
39d0: 61 67 73 20 74 6f 0a 20 20 20 63 68 61 6e 67 65  ags to.   change
39e0: 73 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  s the way it dea
39f0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
3a00: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
3a10: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 20 20 20 74  application.   t
3a20: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
3a30: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
3a40: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
3a50: 63 6b 2c 20 6d 69 67 68 74 20 6d 61 6b 65 0a 20  ck, might make. 
3a60: 20 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20    the open of a 
3a70: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
3a80: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
3a90: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 61 72   this journal ar
3aa0: 65 0a 20 20 20 61 6c 73 6f 20 61 20 6e 6f 2d 6f  e.   also a no-o
3ab0: 70 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20  p.  Any attempt 
3ac0: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
3ad0: 6e 61 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  nal returns [SQL
3ae0: 49 54 45 5f 49 4f 45 52 52 5d 2e 0a 20 20 20 4f  ITE_IOERR]..   O
3af0: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
3b00: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
3b10: 6e 69 7a 65 20 74 68 65 20 61 20 64 61 74 61 62  nize the a datab
3b20: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 0a 20 20  ase file will.  
3b30: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
3b40: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
3b50: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
3b60: 6e 20 61 20 72 61 6e 64 6f 6d 20 6f 72 64 65 72  n a random order
3b70: 0a 20 20 20 61 6e 64 20 73 65 74 20 75 70 20 69  .   and set up i
3b80: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
3b90: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 20 20   accordingly..  
3ba0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
3bb0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
3bc0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
3bd0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 20  s to the xOpen. 
3be0: 20 20 6d 65 74 68 6f 64 3a 0a 20 20 20 3c 75 6c    method:.   <ul
3bf0: 3e 0a 20 20 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.   <li> [SQLIT
3c00: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
3c10: 4c 4f 53 45 5d 0a 20 20 20 3c 6c 69 3e 20 5b 53  LOSE].   <li> [S
3c20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
3c30: 53 49 56 45 5d 0a 20 20 20 3c 2f 75 6c 3e 0a 20  SIVE].   </ul>. 
3c40: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50    The [SQLITE_OP
3c50: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
3c60: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
3c70: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
3c80: 20 20 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20     deleted when 
3c90: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54  it is closed.  T
3ca0: 68 69 73 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  his will always 
3cb0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
3cc0: 0a 20 20 20 64 61 74 61 62 61 73 65 73 20 61 6e  .   databases an
3cd0: 64 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66  d journals and f
3ce0: 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 20  or subjournals. 
3cf0: 20 54 68 65 20 0a 20 20 20 5b 53 51 4c 49 54 45   The .   [SQLITE
3d00: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
3d10: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
3d20: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
3d30: 70 65 6e 65 64 0a 20 20 20 66 6f 72 20 65 78 63  pened.   for exc
3d40: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20  lusive access.  
3d50: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74  This flag is set
3d60: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65   for all files e
3d70: 78 63 65 70 74 0a 20 20 20 66 6f 72 20 74 68 65  xcept.   for the
3d80: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
3d90: 69 6c 65 2e 0a 20 20 20 54 68 65 20 5b 73 71 6c  ile..   The [sql
3da0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
3db0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
3dc0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
3dd0: 74 20 74 6f 0a 20 20 20 78 4f 70 65 6e 20 69 73  t to.   xOpen is
3de0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68   allocated by th
3df0: 65 20 63 61 6c 6c 65 72 2e 20 20 78 4f 70 65 6e  e caller.  xOpen
3e00: 20 6a 75 73 74 20 66 69 6c 6c 73 20 69 74 20 69   just fills it i
3e10: 6e 2e 20 20 54 68 65 0a 20 20 20 63 61 6c 6c 65  n.  The.   calle
3e20: 72 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6d 69  r allocates a mi
3e30: 6e 69 6d 75 6d 20 6f 66 20 73 7a 4f 73 46 69 6c  nimum of szOsFil
3e40: 65 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 20  e bytes for the 
3e50: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 20  [sqlite3_file]. 
3e60: 20 20 73 74 72 75 63 74 75 72 65 2e 0a 7d 0a 0a    structure..}..
3e70: 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68  PARAGRAPH {.  Th
3e80: 65 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  e differences be
3e90: 74 77 65 65 6e 20 61 6e 20 5b 53 51 4c 49 54 45  tween an [SQLITE
3ea0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 20 64  _OPEN_TEMP_DB] d
3eb0: 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 0a 20  atabase and an. 
3ec0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
3ed0: 41 4e 53 49 45 4e 54 5f 44 42 5d 20 64 61 74 61  ANSIENT_DB] data
3ee0: 62 61 73 65 20 69 73 20 74 68 69 73 3a 20 20 54  base is this:  T
3ef0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
3f00: 54 45 4d 50 5f 44 42 5d 0a 20 20 69 73 20 75 73  TEMP_DB].  is us
3f10: 65 64 20 66 6f 72 20 65 78 70 6c 69 63 69 74 6c  ed for explicitl
3f20: 79 20 64 65 63 6c 61 72 65 64 20 61 6e 64 20 6e  y declared and n
3f30: 61 6d 65 64 20 54 45 4d 50 20 74 61 62 6c 65 73  amed TEMP tables
3f40: 20 28 75 73 69 6e 67 20 74 68 65 0a 20 20 43 52   (using the.  CR
3f50: 45 41 54 45 20 54 45 4d 50 20 54 41 42 4c 45 20  EATE TEMP TABLE 
3f60: 73 79 6e 74 61 78 29 20 6f 72 20 66 6f 72 20 6e  syntax) or for n
3f70: 61 6d 65 64 20 74 61 62 6c 65 73 20 69 6e 20 61  amed tables in a
3f80: 20 74 65 6d 70 6f 72 61 72 79 20 64 61 74 61 62   temporary datab
3f90: 61 73 65 0a 20 20 74 68 61 74 20 69 73 20 63 72  ase.  that is cr
3fa0: 65 61 74 65 64 20 62 79 20 6f 70 65 6e 69 6e 67  eated by opening
3fb0: 20 61 20 64 61 74 61 62 61 73 65 20 77 69 74 68   a database with
3fc0: 20 61 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74   a filename that
3fd0: 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 20 20 73   is an empty.  s
3fe0: 74 72 69 6e 67 2e 20 20 41 6e 20 5b 53 51 4c 49  tring.  An [SQLI
3ff0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
4000: 54 5f 44 42 5d 20 68 6f 6c 64 73 20 61 20 64 61  T_DB] holds a da
4010: 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
4020: 74 0a 20 20 53 51 4c 69 74 65 20 63 72 65 61 74  t.  SQLite creat
4030: 65 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  es automatically
4040: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 76 61   in order to eva
4050: 6c 75 61 74 65 20 61 20 73 75 62 71 75 65 72 79  luate a subquery
4060: 20 6f 72 0a 20 20 4f 52 44 45 52 20 42 59 20 6f   or.  ORDER BY o
4070: 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
4080: 65 2e 20 20 42 6f 74 68 20 54 45 4d 50 5f 44 42  e.  Both TEMP_DB
4090: 20 61 6e 64 20 54 52 41 4e 53 49 45 4e 54 5f 44   and TRANSIENT_D
40a0: 42 20 64 61 74 61 62 61 73 65 73 0a 20 20 61 72  B databases.  ar
40b0: 65 20 70 72 69 76 61 74 65 20 61 6e 64 20 61 72  e private and ar
40c0: 65 20 64 65 6c 65 74 65 64 20 61 75 74 6f 6d 61  e deleted automa
40d0: 74 69 63 61 6c 6c 79 2e 20 20 54 45 4d 50 5f 44  tically.  TEMP_D
40e0: 42 20 64 61 74 61 62 61 73 65 73 20 6c 61 73 74  B databases last
40f0: 0a 20 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  .  for the durat
4100: 69 6f 6e 20 6f 66 20 74 68 65 20 64 61 74 61 62  ion of the datab
4110: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
4120: 20 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 64 61   TRANSIENT_DB da
4130: 74 61 62 61 73 65 73 0a 20 20 6c 61 73 74 20 6f  tabases.  last o
4140: 6e 6c 79 20 66 6f 72 20 74 68 65 20 64 75 72 61  nly for the dura
4150: 74 69 6f 6e 20 6f 66 20 61 20 73 69 6e 67 6c 65  tion of a single
4160: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
4170: 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20  }..PARAGRAPH {. 
4180: 20 54 68 65 20 78 44 65 6c 65 74 65 20 6d 65 74   The xDelete met
4190: 68 6f 64 20 69 73 20 75 73 65 64 20 64 65 6c 65  hod is used dele
41a0: 74 65 20 61 20 66 69 6c 65 2e 20 20 54 68 65 20  te a file.  The 
41b0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 69 6c 65  name of the file
41c0: 20 69 73 0a 20 20 67 69 76 65 6e 20 69 6e 20 74   is.  given in t
41d0: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
41e0: 74 65 72 2e 20 20 54 68 65 20 66 69 6c 65 6e 61  ter.  The filena
41f0: 6d 65 20 77 69 6c 6c 20 62 65 20 69 6e 20 55 54  me will be in UT
4200: 46 2d 38 2e 0a 20 20 54 68 65 20 56 46 53 20 6d  F-8..  The VFS m
4210: 75 73 74 20 63 6f 6e 76 65 72 74 20 74 68 65 20  ust convert the 
4220: 66 69 6c 65 6e 61 6d 65 20 69 6e 74 6f 20 77 68  filename into wh
4230: 61 74 65 76 65 72 20 63 68 61 72 61 63 74 65 72  atever character
4240: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 0a   representation.
4250: 20 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    the underlying
4260: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
4270: 6d 20 65 78 70 65 63 74 73 2e 20 20 49 66 20 74  m expects.  If t
4280: 68 65 20 73 79 6e 63 44 69 72 20 70 61 72 61 6d  he syncDir param
4290: 65 74 65 72 20 69 73 0a 20 20 74 72 75 65 2c 20  eter is.  true, 
42a0: 74 68 65 6e 20 74 68 65 20 78 44 65 6c 65 74 65  then the xDelete
42b0: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 6e   method should n
42c0: 6f 74 20 72 65 74 75 72 6e 20 75 6e 74 69 6c 20  ot return until 
42d0: 74 68 65 20 63 68 61 6e 67 65 0a 20 20 74 6f 20  the change.  to 
42e0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
42f0: 6e 74 65 6e 74 73 20 66 6f 72 20 74 68 65 20 64  ntents for the d
4300: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
4310: 69 6e 67 20 74 68 65 0a 20 20 64 65 6c 65 74 65  ing the.  delete
4320: 64 20 66 69 6c 65 20 68 61 76 65 20 62 65 65 6e  d file have been
4330: 20 73 79 6e 63 65 64 20 74 6f 20 64 69 73 6b 20   synced to disk 
4340: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 73 75  in order to ensu
4350: 72 65 20 74 68 61 74 20 74 68 65 0a 20 20 66 69  re that the.  fi
4360: 6c 65 20 64 6f 65 73 20 6e 6f 74 20 22 72 65 61  le does not "rea
4370: 70 70 65 61 72 22 20 69 66 20 61 20 70 6f 77 65  ppear" if a powe
4380: 72 20 66 61 69 6c 75 72 65 20 6f 63 63 75 72 73  r failure occurs
4390: 20 73 6f 6f 6e 20 61 66 74 65 72 2e 0a 7d 0a 0a   soon after..}..
43a0: 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68  PARAGRAPH {.  Th
43b0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
43c0: 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 65 63   is used to chec
43d0: 6b 20 66 6f 72 20 61 63 63 65 73 73 20 70 65 72  k for access per
43e0: 6d 69 73 73 69 6f 6e 73 20 6f 6e 20 61 20 66 69  missions on a fi
43f0: 6c 65 2e 0a 20 20 54 68 65 20 66 69 6c 65 6e 61  le..  The filena
4400: 6d 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  me will be UTF-8
4410: 20 65 6e 63 6f 64 65 64 2e 20 20 54 68 65 20 66   encoded.  The f
4420: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 77 69  lags argument wi
4430: 6c 6c 20 62 65 0a 20 20 5b 53 51 4c 49 54 45 5f  ll be.  [SQLITE_
4440: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 20 74  ACCESS_EXISTS] t
4450: 6f 20 63 68 65 63 6b 20 66 6f 72 20 74 68 65 20  o check for the 
4460: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 74 68 65  existence of the
4470: 20 66 69 6c 65 2c 0a 20 20 5b 53 51 4c 49 54 45   file,.  [SQLITE
4480: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
4490: 45 5d 20 74 6f 20 63 68 65 63 6b 20 74 6f 20 73  E] to check to s
44a0: 65 65 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ee if the file i
44b0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 0a  s both readable.
44c0: 20 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20    and writable, 
44d0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
44e0: 53 5f 52 45 41 44 5d 20 74 6f 20 63 68 65 63 6b  S_READ] to check
44f0: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 66   to see if the f
4500: 69 6c 65 20 69 73 0a 20 20 61 74 20 6c 65 61 73  ile is.  at leas
4510: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  t readable.  The
4520: 20 22 66 69 6c 65 22 20 6e 61 6d 65 64 20 62 79   "file" named by
4530: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
4540: 6d 65 74 65 72 20 6d 69 67 68 74 0a 20 20 62 65  meter might.  be
4550: 20 61 20 64 69 72 65 63 74 6f 72 79 20 6f 72 20   a directory or 
4560: 66 6f 6c 64 65 72 20 6e 61 6d 65 2e 0a 7d 0a 0a  folder name..}..
4570: 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68  PARAGRAPH {.  Th
4580: 65 20 78 47 65 74 54 65 6d 70 4e 61 6d 65 20 6d  e xGetTempName m
4590: 65 74 68 6f 64 20 63 6f 6d 70 75 74 65 73 20 74  ethod computes t
45a0: 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 74 65 6d  he name of a tem
45b0: 70 6f 72 61 72 79 20 66 69 6c 65 20 74 68 61 74  porary file that
45c0: 0a 20 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  .  SQLite can us
45d0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 73 68 6f  e.  The name sho
45e0: 75 6c 64 20 62 65 20 77 72 69 74 74 65 6e 20 69  uld be written i
45f0: 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 67  nto the buffer g
4600: 69 76 65 6e 0a 20 20 62 79 20 74 68 65 20 73 65  iven.  by the se
4610: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
4620: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 69 7a   SQLite will siz
4630: 65 20 74 68 61 74 20 62 75 66 66 65 72 20 74 6f  e that buffer to
4640: 20 68 6f 6c 64 0a 20 20 61 74 20 6c 65 61 73 74   hold.  at least
4650: 20 6d 78 50 61 74 68 6e 61 6d 65 20 62 79 74 65   mxPathname byte
4660: 73 2e 20 20 54 68 65 20 67 65 6e 65 72 61 74 65  s.  The generate
4670: 64 20 66 69 6c 65 6e 61 6d 65 20 73 68 6f 75 6c  d filename shoul
4680: 64 20 62 65 20 69 6e 20 55 54 46 2d 38 2e 0a 20  d be in UTF-8.. 
4690: 20 54 6f 20 61 76 6f 69 64 20 73 65 63 75 72 69   To avoid securi
46a0: 74 79 20 70 72 6f 62 6c 65 6d 73 2c 20 74 68 65  ty problems, the
46b0: 20 67 65 6e 65 72 61 74 65 64 20 74 65 6d 70 6f   generated tempo
46c0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 73 68  rary filename sh
46d0: 6f 75 6c 64 0a 20 20 63 6f 6e 74 61 69 6e 20 65  ould.  contain e
46e0: 6e 6f 75 67 68 20 72 61 6e 64 6f 6d 6e 65 73 73  nough randomness
46f0: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 6e 20 61   to prevent an a
4700: 74 74 61 63 6b 65 72 20 66 72 6f 6d 20 67 75 65  ttacker from gue
4710: 73 73 69 6e 67 20 74 68 65 0a 20 20 74 65 6d 70  ssing the.  temp
4720: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 69  orary filename i
4730: 6e 20 61 64 76 61 6e 63 65 2e 0a 7d 0a 0a 50 41  n advance..}..PA
4740: 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20  RAGRAPH {.  The 
4750: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65  xFullPathname me
4760: 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20  thod is used to 
4770: 63 6f 6e 76 65 72 74 20 61 20 72 65 6c 61 74 69  convert a relati
4780: 76 65 20 70 61 74 68 6e 61 6d 65 0a 20 20 69 6e  ve pathname.  in
4790: 74 6f 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61  to a full pathna
47a0: 6d 65 2e 20 20 54 68 65 20 72 65 73 75 6c 74 69  me.  The resulti
47b0: 6e 67 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65  ng full pathname
47c0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
47d0: 0a 20 20 74 68 65 20 62 75 66 66 65 72 20 70 72  .  the buffer pr
47e0: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 74 68  ovided by the th
47f0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
4800: 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 69 7a 65  SQLite will size
4810: 20 74 68 65 0a 20 20 6f 75 74 70 75 74 20 62 75   the.  output bu
4820: 66 66 65 72 20 74 6f 20 61 74 20 6c 65 61 73 74  ffer to at least
4830: 20 6d 78 50 61 74 68 6e 61 6d 65 20 62 79 74 65   mxPathname byte
4840: 73 2e 20 20 42 6f 74 68 20 74 68 65 20 69 6e 70  s.  Both the inp
4850: 75 74 20 61 6e 64 0a 20 20 6f 75 74 70 75 74 20  ut and.  output 
4860: 6e 61 6d 65 73 20 73 68 6f 75 6c 64 20 62 65 20  names should be 
4870: 69 6e 20 55 54 46 2d 38 2e 0a 7d 0a 0a 50 41 52  in UTF-8..}..PAR
4880: 41 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20 78  AGRAPH {.  The x
4890: 44 6c 4f 70 65 6e 2c 20 78 44 6c 45 72 72 6f 72  DlOpen, xDlError
48a0: 2c 20 78 44 6c 53 79 6d 2c 20 61 6e 64 20 78 44  , xDlSym, and xD
48b0: 6c 43 6c 6f 73 65 20 6d 65 74 68 6f 64 73 20 61  lClose methods a
48c0: 72 65 20 61 6c 6c 20 75 73 65 64 20 66 6f 72 0a  re all used for.
48d0: 20 20 61 63 63 65 73 73 69 6e 67 20 73 68 61 72    accessing shar
48e0: 65 64 20 6c 69 62 72 61 72 69 65 73 20 61 74 20  ed libraries at 
48f0: 72 75 6e 2d 74 69 6d 65 2e 20 20 54 68 65 73 65  run-time.  These
4900: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
4910: 6f 6d 69 74 74 65 64 0a 20 20 28 61 6e 64 20 74  omitted.  (and t
4920: 68 65 69 72 20 70 6f 69 6e 74 65 72 73 20 73 65  heir pointers se
4930: 74 20 74 6f 20 7a 65 72 6f 29 20 69 66 20 74 68  t to zero) if th
4940: 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6d  e library is com
4950: 70 69 6c 65 64 20 77 69 74 68 0a 20 20 5b 53 51  piled with.  [SQ
4960: 4c 49 54 45 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45  LITE_OMIT_LOAD_E
4970: 58 54 45 4e 53 49 4f 4e 5d 20 6f 72 20 69 66 20  XTENSION] or if 
4980: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  the [sqlite3_ena
4990: 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
49a0: 6f 6e 28 29 5d 0a 20 20 69 6e 74 65 72 66 61 63  on()].  interfac
49b0: 65 20 69 73 20 6e 65 76 65 72 20 75 73 65 64 20  e is never used 
49c0: 74 6f 20 65 6e 61 62 6c 65 20 64 79 6e 61 6d 69  to enable dynami
49d0: 63 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  c extension load
49e0: 69 6e 67 2e 20 20 54 68 65 0a 20 20 78 44 6c 4f  ing.  The.  xDlO
49f0: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 70 65 6e 73  pen method opens
4a00: 20 61 20 73 68 61 72 65 64 20 6c 69 62 72 61 72   a shared librar
4a10: 79 20 6f 72 20 44 4c 4c 20 61 6e 64 20 72 65 74  y or DLL and ret
4a20: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
4a30: 6f 0a 20 20 61 20 68 61 6e 64 6c 65 2e 20 20 4e  o.  a handle.  N
4a40: 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 20  ULL is returned 
4a50: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
4a60: 73 2e 20 20 49 66 20 74 68 65 20 6f 70 65 6e 20  s.  If the open 
4a70: 66 61 69 6c 73 2c 0a 20 20 74 68 65 20 78 44 6c  fails,.  the xDl
4a80: 45 72 72 6f 72 20 6d 65 74 68 6f 64 20 63 61 6e  Error method can
4a90: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
4aa0: 69 6e 20 61 20 74 65 78 74 20 65 72 72 6f 72 20  in a text error 
4ab0: 6d 65 73 73 61 67 65 2e 0a 20 20 54 68 65 20 6d  message..  The m
4ac0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
4ad0: 6e 20 69 6e 74 6f 20 74 68 65 20 7a 45 72 72 4d  n into the zErrM
4ae0: 73 67 20 62 75 66 66 65 72 20 6f 66 20 74 68 65  sg buffer of the
4af0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
4b00: 0a 20 20 77 68 69 63 68 20 69 73 20 61 74 20 6c  .  which is at l
4b10: 65 61 73 74 20 6e 42 79 74 65 20 62 79 74 65 73  east nByte bytes
4b20: 20 69 6e 20 6c 65 6e 67 74 68 2e 20 20 54 68 65   in length.  The
4b30: 20 78 44 6c 53 79 6d 20 72 65 74 75 72 6e 73 20   xDlSym returns 
4b40: 61 20 70 6f 69 6e 74 65 72 0a 20 20 74 6f 20 61  a pointer.  to a
4b50: 20 73 79 6d 62 6f 6c 20 69 6e 20 74 68 65 20 73   symbol in the s
4b60: 68 61 72 65 64 20 6c 69 62 72 61 72 79 2e 20 20  hared library.  
4b70: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
4b80: 73 79 6d 62 6f 6c 20 69 73 20 67 69 76 65 6e 0a  symbol is given.
4b90: 20 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20    by the second 
4ba0: 70 61 72 61 6d 65 74 65 72 2e 20 20 55 54 46 2d  parameter.  UTF-
4bb0: 38 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 73  8 encoding is as
4bc0: 73 75 6d 65 64 2e 20 20 49 66 20 74 68 65 20 73  sumed.  If the s
4bd0: 79 6d 62 6f 6c 0a 20 20 69 73 20 6e 6f 74 20 66  ymbol.  is not f
4be0: 6f 75 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ound a NULL poin
4bf0: 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
4c00: 20 20 54 68 65 20 78 44 6c 43 6c 6f 73 65 20 72    The xDlClose r
4c10: 6f 75 74 69 6e 65 20 63 6c 6f 73 65 73 0a 20 20  outine closes.  
4c20: 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
4c30: 72 79 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48  ry..}..PARAGRAPH
4c40: 20 7b 0a 20 20 54 68 65 20 78 52 61 6e 64 6f 6d   {.  The xRandom
4c50: 6e 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 75  ness method is u
4c60: 73 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  sed exactly once
4c70: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 20 74   to initialize t
4c80: 68 65 20 0a 20 20 70 73 65 75 64 6f 2d 72 61 6e  he .  pseudo-ran
4c90: 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
4ca0: 61 74 6f 72 20 28 50 52 4e 47 29 20 69 6e 73 69  ator (PRNG) insi
4cb0: 64 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 4f  de of SQLite.  O
4cc0: 6e 6c 79 0a 20 20 74 68 65 20 78 52 61 6e 64 6f  nly.  the xRando
4cd0: 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 6e 20  mness method on 
4ce0: 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
4cf0: 69 73 20 75 73 65 64 2e 20 20 54 68 65 20 78 52  is used.  The xR
4d00: 61 6e 64 6f 6d 6e 65 73 73 0a 20 20 6d 65 74 68  andomness.  meth
4d10: 6f 64 73 20 6f 6e 20 6f 74 68 65 72 20 56 46 53  ods on other VFS
4d20: 65 73 20 61 72 65 20 6e 65 76 65 72 20 61 63 63  es are never acc
4d30: 65 73 73 65 64 20 62 79 20 53 51 4c 69 74 65 2e  essed by SQLite.
4d40: 0a 20 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  .  The xRandomne
4d50: 73 73 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ss routine reque
4d60: 73 74 73 20 74 68 61 74 20 6e 42 79 74 65 20 62  sts that nByte b
4d70: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
4d80: 73 73 0a 20 20 62 65 20 77 72 69 74 74 65 6e 20  ss.  be written 
4d90: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
4da0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
4db0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
4dc0: 72 20 6f 66 0a 20 20 62 79 74 65 73 20 6f 66 20  r of.  bytes of 
4dd0: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
4de0: 6e 65 64 2e 20 20 54 68 65 20 71 75 61 6c 69 74  ned.  The qualit
4df0: 79 20 6f 66 20 74 68 65 20 72 61 6e 64 6f 6d 6e  y of the randomn
4e00: 65 73 73 20 73 6f 20 6f 62 74 61 69 6e 65 64 0a  ess so obtained.
4e10: 20 20 77 69 6c 6c 20 64 65 74 65 72 6d 69 6e 65    will determine
4e20: 20 74 68 65 20 71 75 61 6c 69 74 79 20 6f 66 20   the quality of 
4e30: 74 68 65 20 72 61 6e 64 6f 6d 6e 65 73 73 20 67  the randomness g
4e40: 65 6e 65 72 61 74 65 64 20 62 79 20 62 75 69 6c  enerated by buil
4e50: 74 2d 69 6e 20 0a 20 20 53 51 4c 69 74 65 20 66  t-in .  SQLite f
4e60: 75 6e 63 74 69 6f 6e 73 20 73 75 63 68 20 61 73  unctions such as
4e70: 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
4e80: 6e 64 6f 6d 62 6c 6f 62 28 29 2e 20 20 53 51 4c  ndomblob().  SQL
4e90: 69 74 65 20 61 6c 73 6f 0a 20 20 75 73 65 73 20  ite also.  uses 
4ea0: 69 74 73 20 50 52 4e 47 20 74 6f 20 67 65 6e 65  its PRNG to gene
4eb0: 72 61 74 65 20 74 65 6d 70 6f 72 61 72 79 20 66  rate temporary f
4ec0: 69 6c 65 20 6e 61 6d 65 73 2e 2e 20 20 4f 6e 20  ile names..  On 
4ed0: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 0a 20  some platforms. 
4ee0: 20 28 65 78 3a 20 57 69 6e 64 6f 77 73 29 20 53   (ex: Windows) S
4ef0: 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
4f00: 61 74 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  at temporary fil
4f10: 65 20 6e 61 6d 65 73 20 61 72 65 20 75 6e 69 71  e names are uniq
4f20: 75 65 0a 20 20 77 69 74 68 6f 75 74 20 61 63 74  ue.  without act
4f30: 75 61 6c 6c 79 20 74 65 73 74 69 6e 67 20 66 6f  ually testing fo
4f40: 72 20 63 6f 6c 6c 69 73 69 6f 6e 73 2c 20 73 6f  r collisions, so
4f50: 20 69 74 20 69 73 20 69 6d 70 6f 72 74 61 6e 74   it is important
4f60: 20 74 6f 20 68 61 76 65 0a 20 20 67 6f 6f 64 2d   to have.  good-
4f70: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
4f80: 73 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 72  ss even if the r
4f90: 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
4fa0: 6f 6d 62 6c 6f 62 28 29 20 0a 20 20 66 75 6e 63  omblob() .  func
4fb0: 74 69 6f 6e 73 20 61 72 65 20 6e 65 76 65 72 20  tions are never 
4fc0: 75 73 65 64 2e 0a 7d 0a 0a 50 41 52 41 47 52 41  used..}..PARAGRA
4fd0: 50 48 20 7b 0a 20 20 54 68 65 20 78 53 6c 65 65  PH {.  The xSlee
4fe0: 70 20 6d 65 74 68 6f 64 20 69 73 20 75 73 65 64  p method is used
4ff0: 20 74 6f 20 73 75 73 70 65 6e 64 20 74 68 65 20   to suspend the 
5000: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 66  calling thread f
5010: 6f 72 20 61 74 0a 20 20 6c 65 61 73 74 20 74 68  or at.  least th
5020: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
5030: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
5040: 20 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20   This method is 
5050: 75 73 65 64 20 74 6f 0a 20 20 69 6d 70 6c 65 6d  used to.  implem
5060: 65 6e 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ent the [sqlite3
5070: 5f 73 6c 65 65 70 28 29 5d 20 61 6e 64 20 5b 73  _sleep()] and [s
5080: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
5090: 6f 75 74 28 29 5d 20 41 50 49 73 2e 0a 20 20 49  out()] APIs..  I
50a0: 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 5b 73  n the case of [s
50b0: 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 5d 20  qlite3_sleep()] 
50c0: 74 68 65 20 78 53 6c 65 65 70 20 6d 65 74 68 6f  the xSleep metho
50d0: 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
50e0: 0a 20 20 56 46 53 20 69 73 20 61 6c 77 61 79 73  .  VFS is always
50f0: 20 75 73 65 64 2e 20 20 49 66 20 74 68 65 20 75   used.  If the u
5100: 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
5110: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
5120: 0a 20 20 6d 69 63 72 6f 73 65 63 6f 6e 64 20 72  .  microsecond r
5130: 65 73 6f 6c 75 74 69 6f 6e 20 73 6c 65 65 70 20  esolution sleep 
5140: 63 61 70 61 62 69 6c 69 74 79 2c 20 74 68 65 6e  capability, then
5150: 20 74 68 65 20 73 6c 65 65 70 20 74 69 6d 65 20   the sleep time 
5160: 73 68 6f 75 6c 64 0a 20 20 62 65 20 72 6f 75 6e  should.  be roun
5170: 64 65 64 20 75 70 2e 20 20 78 53 6c 65 65 70 20  ded up.  xSleep 
5180: 72 65 74 75 72 6e 73 20 74 68 69 73 20 72 6f 75  returns this rou
5190: 6e 64 65 64 2d 75 70 20 76 61 6c 75 65 2e 0a 7d  nded-up value..}
51a0: 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20  ..PARAGRAPH {.  
51b0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
51c0: 20 6d 65 74 68 6f 64 20 66 69 6e 64 73 20 74 68   method finds th
51d0: 65 20 63 75 72 72 65 6e 74 20 74 69 6d 65 20 61  e current time a
51e0: 6e 64 20 64 61 74 65 20 61 6e 64 20 77 72 69 74  nd date and writ
51f0: 65 73 0a 20 20 74 68 65 20 72 65 73 75 6c 74 20  es.  the result 
5200: 61 73 20 64 6f 75 62 6c 65 2d 70 72 65 63 69 73  as double-precis
5210: 69 6f 6e 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  ion floating poi
5220: 6e 74 20 76 61 6c 75 65 20 69 6e 74 6f 20 70 6f  nt value into po
5230: 69 6e 74 65 72 0a 20 20 70 72 6f 76 69 64 65 64  inter.  provided
5240: 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
5250: 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 74  arameter.  The t
5260: 69 6d 65 20 61 6e 64 20 64 61 74 65 20 69 73 20  ime and date is 
5270: 69 6e 0a 20 20 63 6f 6f 72 64 69 6e 61 74 65 64  in.  coordinated
5280: 20 75 6e 69 76 65 72 73 61 6c 20 74 69 6d 65 20   universal time 
5290: 28 55 54 43 29 20 61 6e 64 20 69 73 20 61 20 66  (UTC) and is a f
52a0: 72 61 63 74 69 6f 6e 61 6c 20 4a 75 6c 69 61 6e  ractional Julian
52b0: 20 64 61 79 20 6e 75 6d 62 65 72 2e 0a 7d 0a 0a   day number..}..
52c0: 48 45 41 44 49 4e 47 20 33 20 7b 54 68 65 20 4f  HEADING 3 {The O
52d0: 70 65 6e 20 46 69 6c 65 20 4f 62 6a 65 63 74 7d  pen File Object}
52e0: 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20  ..PARAGRAPH {.  
52f0: 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 70  The result of op
5300: 65 6e 69 6e 67 20 61 20 66 69 6c 65 20 69 73 20  ening a file is 
5310: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  an instance of a
5320: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
5330: 20 6f 62 6a 65 63 74 2e 0a 20 20 54 68 65 20 5b   object..  The [
5340: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
5350: 6a 65 63 74 20 69 73 20 61 6e 20 61 62 73 74 72  ject is an abstr
5360: 61 63 74 20 62 61 73 65 20 63 6c 61 73 73 20 64  act base class d
5370: 65 66 69 6e 65 64 20 61 73 20 66 6f 6c 6c 6f 77  efined as follow
5380: 73 3a 0a 7d 0a 0a 43 4f 44 45 20 7b 0a 74 79 70  s:.}..CODE {.typ
5390: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
53a0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
53b0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
53c0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
53d0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
53e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
53f0: 70 4d 65 74 68 6f 64 73 3b 0a 7d 3b 0a 7d 0a 0a  pMethods;.};.}..
5400: 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 45 61  PARAGRAPH {.  Ea
5410: 63 68 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ch VFS implement
5420: 61 74 69 6f 6e 20 77 69 6c 6c 20 73 75 62 63 6c  ation will subcl
5430: 61 73 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ass the [sqlite3
5440: 5f 66 69 6c 65 5d 20 62 79 20 61 64 64 69 6e 67  _file] by adding
5450: 0a 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  additional fi
5460: 65 6c 64 73 20 61 74 20 74 68 65 20 65 6e 64 20  elds at the end 
5470: 74 6f 20 68 6f 6c 64 20 77 68 61 74 65 76 65 72  to hold whatever
5480: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 65   information the
5490: 20 56 46 53 0a 20 20 6e 65 65 64 73 20 74 6f 20   VFS.  needs to 
54a0: 6b 6e 6f 77 20 61 62 6f 75 74 20 61 6e 20 6f 70  know about an op
54b0: 65 6e 20 66 69 6c 65 2e 20 20 49 74 20 64 6f 65  en file.  It doe
54c0: 73 20 6e 6f 74 20 6d 61 74 74 65 72 20 77 68 61  s not matter wha
54d0: 74 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 20 20  t information.  
54e0: 69 73 20 73 74 6f 72 65 64 20 61 73 20 6c 6f 6e  is stored as lon
54f0: 67 20 61 73 20 74 68 65 20 74 6f 74 61 6c 20 73  g as the total s
5500: 69 7a 65 20 6f 66 20 74 68 65 20 73 74 72 75 63  ize of the struc
5510: 74 75 72 65 20 64 6f 65 73 20 6e 6f 74 20 65 78  ture does not ex
5520: 63 65 65 64 0a 20 20 74 68 65 20 73 7a 4f 73 46  ceed.  the szOsF
5530: 69 6c 65 20 76 61 6c 75 65 20 72 65 63 6f 72 64  ile value record
5540: 65 64 20 69 6e 20 74 68 65 20 5b 73 71 6c 69 74  ed in the [sqlit
5550: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
5560: 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20  }..PARAGRAPH {. 
5570: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   The [sqlite3_io
5580: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5590: 20 69 73 20 61 20 73 74 72 75 63 74 75 72 65 20   is a structure 
55a0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 70 6f  that contains po
55b0: 69 6e 74 65 72 73 0a 20 20 74 6f 20 6d 65 74 68  inters.  to meth
55c0: 6f 64 73 20 66 6f 72 20 72 65 61 64 69 6e 67 2c  ods for reading,
55d0: 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 6f 74   writing, and ot
55e0: 68 65 72 77 69 73 65 20 64 65 61 6c 69 6e 67 20  herwise dealing 
55f0: 77 69 74 68 20 66 69 6c 65 73 2e 0a 20 20 54 68  with files..  Th
5600: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 64 65 66  is object is def
5610: 69 6e 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ined as follows:
5620: 0a 7d 0a 0a 43 4f 44 45 20 7b 0a 74 79 70 65 64  .}..CODE {.typed
5630: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
5640: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
5650: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
5660: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
5670: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
5680: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
5690: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
56a0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
56b0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
56c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
56d0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
56e0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
56f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
5700: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
5710: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
5720: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
5730: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
5740: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
5750: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
5760: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
5770: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
5780: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
5790: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
57a0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
57b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
57c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
57d0: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
57e0: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
57f0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
5800: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
5810: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
5820: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
5830: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
5840: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
5850: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
5860: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
5870: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
5880: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
5890: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
58a0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
58b0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
58c0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
58d0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
58e0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
58f0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
5900: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
5910: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 7d 0a 0a 50 41  ases */.};.}..PA
5920: 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20  RAGRAPH {.  The 
5930: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 6f  iVersion field o
5940: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
5950: 74 68 6f 64 73 5d 20 69 73 20 70 72 6f 76 69 64  thods] is provid
5960: 65 64 20 61 73 20 69 6e 73 75 72 61 6e 63 65 0a  ed as insurance.
5970: 20 20 61 67 61 69 6e 73 74 20 66 75 74 75 72 65    against future
5980: 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 2e 20 20   enhancements.  
5990: 54 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  The iVersion val
59a0: 75 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  ue should always
59b0: 20 62 65 0a 20 20 31 20 66 6f 72 20 53 51 4c 69   be.  1 for SQLi
59c0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 0a  te version 3.5..
59d0: 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20  }..PARAGRAPH {. 
59e0: 20 54 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68   The xClose meth
59f0: 6f 64 20 63 6c 6f 73 65 73 20 74 68 65 20 66 69  od closes the fi
5a00: 6c 65 2e 20 20 54 68 65 20 73 70 61 63 65 20 66  le.  The space f
5a10: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
5a20: 66 69 6c 65 5d 0a 20 20 73 74 72 75 63 74 75 72  file].  structur
5a30: 65 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64  e is deallocated
5a40: 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   by the caller. 
5a50: 20 42 75 74 20 69 66 20 74 68 65 20 5b 73 71 6c   But if the [sql
5a60: 69 74 65 33 5f 66 69 6c 65 5d 0a 20 20 63 6f 6e  ite3_file].  con
5a70: 74 61 69 6e 73 20 70 6f 69 6e 74 65 72 73 20 74  tains pointers t
5a80: 6f 20 6f 74 68 65 72 20 61 6c 6c 6f 63 61 74 65  o other allocate
5a90: 64 20 6d 65 6d 6f 72 79 20 6f 72 20 72 65 73 6f  d memory or reso
5aa0: 75 72 63 65 73 2c 20 74 68 6f 73 65 0a 20 20 61  urces, those.  a
5ab0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  llocations shoul
5ac0: 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
5ad0: 20 74 68 65 20 78 43 6c 6f 73 65 20 6d 65 74 68   the xClose meth
5ae0: 6f 64 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48  od..}..PARAGRAPH
5af0: 20 7b 0a 20 20 54 68 65 20 78 52 65 61 64 20 6d   {.  The xRead m
5b00: 65 74 68 6f 64 20 72 65 61 64 73 20 69 41 6d 74  ethod reads iAmt
5b10: 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
5b20: 66 69 6c 65 20 62 65 67 69 6e 6e 69 6e 67 20 61  file beginning a
5b30: 74 20 61 20 62 79 74 65 0a 20 20 6f 66 66 73 65  t a byte.  offse
5b40: 74 20 74 6f 20 69 4f 66 73 74 2e 20 20 54 68 65  t to iOfst.  The
5b50: 20 64 61 74 61 20 72 65 61 64 20 69 73 20 73 74   data read is st
5b60: 6f 72 65 64 20 69 6e 20 74 68 65 20 70 6f 69 6e  ored in the poin
5b70: 74 65 72 20 6f 66 20 74 68 65 0a 20 20 73 65 63  ter of the.  sec
5b80: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
5b90: 78 52 65 61 64 20 72 65 74 75 72 6e 73 20 74 68  xRead returns th
5ba0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  e [SQLITE_OK] on
5bb0: 20 73 75 63 63 65 73 73 2c 0a 20 20 5b 53 51 4c   success,.  [SQL
5bc0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
5bd0: 52 45 41 44 5d 20 69 66 20 69 74 20 77 61 73 20  READ] if it was 
5be0: 6e 6f 74 20 61 62 6c 65 20 74 6f 20 72 65 61 64  not able to read
5bf0: 20 74 68 65 20 66 75 6c 6c 20 6e 75 6d 62 65 72   the full number
5c00: 0a 20 20 6f 66 20 62 79 74 65 73 20 62 65 63 61  .  of bytes beca
5c10: 75 73 65 20 69 74 20 72 65 61 63 68 65 64 20 65  use it reached e
5c20: 6e 64 2d 6f 66 2d 66 69 6c 65 2c 20 6f 72 20 5b  nd-of-file, or [
5c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
5c40: 44 5d 20 66 6f 72 0a 20 20 61 6e 79 20 6f 74 68  D] for.  any oth
5c50: 65 72 20 65 72 72 6f 72 2e 0a 7d 0a 0a 50 41 52  er error..}..PAR
5c60: 41 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20 78  AGRAPH {.  The x
5c70: 57 72 69 74 65 20 6d 65 74 68 6f 64 20 77 72 69  Write method wri
5c80: 74 65 73 20 69 41 6d 74 20 62 79 74 65 73 20 6f  tes iAmt bytes o
5c90: 66 20 64 61 74 61 20 66 72 6f 6d 20 74 68 65 20  f data from the 
5ca0: 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
5cb0: 0a 20 20 69 6e 74 6f 20 74 68 65 20 66 69 6c 65  .  into the file
5cc0: 20 62 65 67 69 6e 6e 69 6e 67 20 61 74 20 61 6e   beginning at an
5cd0: 20 6f 66 66 73 65 74 20 6f 66 20 69 4f 66 73 74   offset of iOfst
5ce0: 20 62 79 74 65 73 2e 20 20 49 66 20 74 68 65 20   bytes.  If the 
5cf0: 73 69 7a 65 20 6f 66 0a 20 20 74 68 65 20 66 69  size of.  the fi
5d00: 6c 65 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  le is less than 
5d10: 69 4f 66 73 74 20 62 79 74 65 73 20 70 72 69 6f  iOfst bytes prio
5d20: 72 20 74 6f 20 74 68 65 20 77 72 69 74 65 2c 20  r to the write, 
5d30: 74 68 65 6e 20 78 57 72 69 74 65 20 73 68 6f 75  then xWrite shou
5d40: 6c 64 0a 20 20 65 6e 73 75 72 65 20 74 68 61 74  ld.  ensure that
5d50: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5d60: 65 6e 64 65 64 20 77 69 74 68 20 7a 65 72 6f 73  ended with zeros
5d70: 20 75 70 20 74 6f 20 69 4f 66 73 74 20 62 79 74   up to iOfst byt
5d80: 65 73 20 70 72 69 6f 72 0a 20 20 74 6f 20 62 65  es prior.  to be
5d90: 67 69 6e 6e 69 6e 67 20 69 74 73 20 77 72 69 74  ginning its writ
5da0: 65 2e 20 20 78 57 72 69 74 65 20 63 6f 6e 74 69  e.  xWrite conti
5db0: 6e 75 65 73 20 74 6f 20 65 78 74 65 6e 64 73 20  nues to extends 
5dc0: 74 68 65 20 66 69 6c 65 20 61 73 0a 20 20 6e 65  the file as.  ne
5dd0: 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
5de0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5df0: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
5e00: 20 69 41 6d 74 2b 69 4f 66 73 74 20 62 79 74 65   iAmt+iOfst byte
5e10: 73 20 0a 20 20 61 74 20 74 68 65 20 63 6f 6e 63  s .  at the conc
5e20: 6c 75 73 69 6f 6e 20 6f 66 20 74 68 65 20 78 57  lusion of the xW
5e30: 72 69 74 65 20 63 61 6c 6c 2e 20 20 54 68 65 20  rite call.  The 
5e40: 78 57 72 69 74 65 20 6d 65 74 68 6f 64 20 72 65  xWrite method re
5e50: 74 75 72 6e 73 0a 20 20 5b 53 51 4c 49 54 45 5f  turns.  [SQLITE_
5e60: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 20  OK] on success. 
5e70: 20 49 66 20 74 68 65 20 77 72 69 74 65 20 63 61   If the write ca
5e80: 6e 6e 6f 74 20 63 6f 6d 70 6c 65 74 65 20 62 65  nnot complete be
5e90: 63 61 75 73 65 20 74 68 65 0a 20 20 75 6e 64 65  cause the.  unde
5ea0: 72 6c 79 69 6e 67 20 73 74 6f 72 61 67 65 20 6d  rlying storage m
5eb0: 65 64 69 75 6d 20 69 73 20 66 75 6c 6c 2c 20 74  edium is full, t
5ec0: 68 65 6e 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  hen [SQLITE_FULL
5ed0: 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 20  ] is returned.. 
5ee0: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57   [SQLITE_IOERR_W
5ef0: 52 49 54 45 5d 20 73 68 6f 75 6c 64 20 62 65 20  RITE] should be 
5f00: 72 65 74 75 72 6e 65 64 20 66 6f 72 20 61 6e 79  returned for any
5f10: 20 6f 74 68 65 72 20 65 72 72 6f 72 2e 0a 7d 0a   other error..}.
5f20: 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 54  .PARAGRAPH {.  T
5f30: 68 65 20 78 54 72 75 6e 63 61 74 65 20 6d 65 74  he xTruncate met
5f40: 68 6f 64 20 74 72 75 6e 63 61 74 65 73 20 61 20  hod truncates a 
5f50: 66 69 6c 65 20 74 6f 20 62 65 20 6e 42 79 74 65  file to be nByte
5f60: 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
5f70: 2e 0a 20 20 49 66 20 74 68 65 20 66 69 6c 65 20  ..  If the file 
5f80: 69 73 20 61 6c 72 65 61 64 79 20 6e 42 79 74 65  is already nByte
5f90: 20 62 79 74 65 73 20 6f 72 20 6c 65 73 73 20 69   bytes or less i
5fa0: 6e 20 6c 65 6e 67 74 68 20 74 68 65 6e 20 74 68  n length then th
5fb0: 69 73 0a 20 20 6d 65 74 68 6f 64 20 69 73 20 61  is.  method is a
5fc0: 20 6e 6f 2d 6f 70 2e 20 20 54 68 65 20 78 54 72   no-op.  The xTr
5fd0: 75 6e 63 61 74 65 20 6d 65 74 68 6f 64 20 72 65  uncate method re
5fe0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
5ff0: 5d 20 6f 6e 0a 20 20 73 75 63 63 65 73 73 20 61  ] on.  success a
6000: 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  nd [SQLITE_IOERR
6010: 5f 54 52 55 4e 43 41 54 45 5d 20 69 66 20 61 6e  _TRUNCATE] if an
6020: 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
6030: 67 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20  g..}..PARAGRAPH 
6040: 7b 0a 20 20 54 68 65 20 78 53 79 6e 63 20 6d 65  {.  The xSync me
6050: 74 68 6f 64 20 69 73 20 75 73 65 64 20 74 6f 20  thod is used to 
6060: 66 6f 72 63 65 20 70 72 65 76 69 6f 75 73 6c 79  force previously
6070: 20 77 72 69 74 74 65 6e 20 64 61 74 61 20 6f 75   written data ou
6080: 74 20 6f 66 0a 20 20 6f 70 65 72 61 74 69 6e 67  t of.  operating
6090: 20 73 79 73 74 65 6d 20 63 61 63 68 65 20 61 6e   system cache an
60a0: 64 20 69 6e 74 6f 20 6e 6f 6e 2d 76 6f 6c 61 74  d into non-volat
60b0: 69 6c 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  ile memory.  The
60c0: 20 73 65 63 6f 6e 64 0a 20 20 70 61 72 61 6d 65   second.  parame
60d0: 74 65 72 20 69 73 20 75 73 75 61 6c 6c 79 20 5b  ter is usually [
60e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
60f0: 41 4c 5d 2e 20 20 49 66 20 74 68 65 20 73 65 63  AL].  If the sec
6100: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 20 20  ond parameter.  
6110: 69 73 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  is [SQLITE_SYNC_
6120: 46 55 4c 4c 5d 20 74 68 65 6e 20 74 68 65 20 78  FULL] then the x
6130: 53 79 6e 63 20 6d 65 74 68 6f 64 20 73 68 6f 75  Sync method shou
6140: 6c 64 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  ld make sure tha
6150: 74 0a 20 20 64 61 74 61 20 68 61 73 20 61 6c 73  t.  data has als
6160: 6f 20 62 65 65 6e 20 66 6c 75 73 68 65 64 20 74  o been flushed t
6170: 68 72 6f 75 67 68 20 74 68 65 20 64 69 73 6b 20  hrough the disk 
6180: 63 6f 6e 74 72 6f 6c 6c 65 72 73 20 63 61 63 68  controllers cach
6190: 65 2e 0a 20 20 54 68 65 20 5b 53 51 4c 49 54 45  e..  The [SQLITE
61a0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 20 70 61 72 61  _SYNC_FULL] para
61b0: 6d 65 74 65 72 20 69 73 20 74 68 65 20 65 71 75  meter is the equ
61c0: 69 76 61 6c 65 6e 74 20 6f 66 20 74 68 65 20 46  ivalent of the F
61d0: 5f 46 55 4c 4c 53 59 4e 43 0a 20 20 69 6f 63 74  _FULLSYNC.  ioct
61e0: 6c 28 29 20 6f 6e 20 4d 61 63 20 4f 53 20 58 2e  l() on Mac OS X.
61f0: 20 54 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   The xSync metho
6200: 64 20 72 65 74 75 72 6e 73 0a 20 20 5b 53 51 4c  d returns.  [SQL
6210: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
6220: 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ss and [SQLITE_I
6230: 4f 45 52 52 5f 46 53 59 4e 43 5d 20 69 66 20 61  OERR_FSYNC] if a
6240: 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
6250: 6e 67 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48  ng..}..PARAGRAPH
6260: 20 7b 0a 20 20 54 68 65 20 78 46 69 6c 65 53 69   {.  The xFileSi
6270: 7a 65 28 29 20 6d 65 74 68 6f 64 20 64 65 74 65  ze() method dete
6280: 72 6d 69 6e 65 73 20 74 68 65 20 63 75 72 72 65  rmines the curre
6290: 6e 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  nt size of the f
62a0: 69 6c 65 0a 20 20 69 6e 20 62 79 74 65 73 20 61  ile.  in bytes a
62b0: 6e 64 20 77 72 69 74 65 73 20 74 68 61 74 20 76  nd writes that v
62c0: 61 6c 75 65 20 69 6e 74 6f 20 2a 70 53 69 7a 65  alue into *pSize
62d0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 5b 53  .  It returns [S
62e0: 51 4c 49 54 45 5f 4f 4b 5d 0a 20 20 6f 6e 20 73  QLITE_OK].  on s
62f0: 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
6300: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 5d 20  TE_IOERR_FSTAT] 
6310: 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
6320: 73 20 77 72 6f 6e 67 2e 0a 7d 0a 0a 50 41 52 41  s wrong..}..PARA
6330: 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20 78 4c  GRAPH {.  The xL
6340: 6f 63 6b 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 20  ock and xUnlock 
6350: 6d 65 74 68 6f 64 73 20 61 72 65 20 75 73 65 64  methods are used
6360: 20 74 6f 20 73 65 74 20 61 6e 64 20 63 6c 65 61   to set and clea
6370: 72 20 66 69 6c 65 20 6c 6f 63 6b 73 2e 0a 20 20  r file locks..  
6380: 53 51 4c 69 74 65 20 73 75 70 70 6f 72 74 73 20  SQLite supports 
6390: 66 69 76 65 20 6c 65 76 65 6c 73 20 6f 66 20 66  five levels of f
63a0: 69 6c 65 20 6c 6f 63 6b 73 2c 20 69 6e 20 6f 72  ile locks, in or
63b0: 64 65 72 3a 0a 20 20 3c 75 6c 3e 0a 20 20 3c 6c  der:.  <ul>.  <l
63c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
63d0: 4e 4f 4e 45 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51  NONE].  <li> [SQ
63e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
63f0: 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  ].  <li> [SQLITE
6400: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 0a  _LOCK_RESERVED].
6410: 20 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c    <li> [SQLITE_L
6420: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 0a 20 20 3c  OCK_PENDING].  <
6430: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6440: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 20 20 3c 2f  _EXCLUSIVE].  </
6450: 75 6c 3e 0a 20 20 54 68 65 20 75 6e 64 65 72 6c  ul>.  The underl
6460: 79 69 6e 67 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ying implementat
6470: 69 6f 6e 20 63 61 6e 20 73 75 70 70 6f 72 74 20  ion can support 
6480: 73 6f 6d 65 20 73 75 62 73 65 74 20 6f 66 20 74  some subset of t
6490: 68 65 73 65 20 6c 6f 63 6b 69 6e 67 0a 20 20 6c  hese locking.  l
64a0: 65 76 65 6c 73 20 61 73 20 6c 6f 6e 67 20 61 73  evels as long as
64b0: 20 69 74 20 6d 65 65 74 73 20 74 68 65 20 6f 74   it meets the ot
64c0: 68 65 72 20 72 65 71 75 69 72 65 6d 65 6e 74 73  her requirements
64d0: 20 6f 66 20 74 68 69 73 20 70 61 72 61 67 72 61   of this paragra
64e0: 70 68 2e 0a 20 20 54 68 65 20 6c 6f 63 6b 69 6e  ph..  The lockin
64f0: 67 20 6c 65 76 65 6c 20 69 73 20 73 70 65 63 69  g level is speci
6500: 66 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  fied as the seco
6510: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62  nd argument to b
6520: 6f 74 68 20 78 4c 6f 63 6b 0a 20 20 61 6e 64 20  oth xLock.  and 
6530: 78 55 6e 6c 6f 63 6b 2e 20 20 54 68 65 20 78 4c  xUnlock.  The xL
6540: 6f 63 6b 20 6d 65 74 68 6f 64 20 69 6e 63 72 65  ock method incre
6550: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 69 6e 67  ases the locking
6560: 20 6c 65 76 65 6c 20 74 6f 20 74 68 65 0a 20 20   level to the.  
6570: 73 70 65 63 69 66 69 65 64 20 6c 6f 63 6b 69 6e  specified lockin
6580: 67 20 6c 65 76 65 6c 20 6f 72 20 68 69 67 68 65  g level or highe
6590: 72 2e 20 20 54 68 65 20 78 55 6e 6c 6f 63 6b 20  r.  The xUnlock 
65a0: 6d 65 74 68 6f 64 20 64 65 63 72 65 61 73 65 73  method decreases
65b0: 20 74 68 65 0a 20 20 6c 6f 63 6b 69 6e 67 20 6c   the.  locking l
65c0: 65 76 65 6c 20 74 6f 20 6e 6f 20 6c 6f 77 65 72  evel to no lower
65d0: 20 74 68 61 6e 20 74 68 65 20 6c 65 76 65 6c 20   than the level 
65e0: 73 70 65 63 69 66 69 65 64 2e 20 20 0a 20 20 5b  specified.  .  [
65f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6600: 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
6610: 20 66 69 6c 65 20 69 73 20 75 6e 6c 6f 63 6b 65   file is unlocke
6620: 64 2e 20 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  d.  [SQLITE_LOCK
6630: 5f 53 48 41 52 45 44 5d 0a 20 20 67 69 76 65 73  _SHARED].  gives
6640: 20 70 65 72 6d 69 73 73 69 6f 6e 20 74 6f 20 72   permission to r
6650: 65 61 64 20 74 68 65 20 66 69 6c 65 2e 20 20 4d  ead the file.  M
6660: 75 6c 74 69 70 6c 65 20 64 61 74 61 62 61 73 65  ultiple database
6670: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 61 6e   connections can
6680: 0a 20 20 68 6f 6c 64 20 5b 53 51 4c 49 54 45 5f  .  hold [SQLITE_
6690: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 20 61 74 20  LOCK_SHARED] at 
66a0: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 20  the same time.. 
66b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
66c0: 53 45 52 56 45 44 5d 20 69 73 20 6c 69 6b 65 20  SERVED] is like 
66d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
66e0: 52 45 44 5d 20 69 6e 20 74 68 61 74 20 69 74 73  RED] in that its
66f0: 20 69 73 20 70 65 72 6d 69 73 73 69 6f 6e 0a 20   is permission. 
6700: 20 74 6f 20 72 65 61 64 20 74 68 65 20 66 69 6c   to read the fil
6710: 65 2e 20 20 42 75 74 20 6f 6e 6c 79 20 61 20 73  e.  But only a s
6720: 69 6e 67 6c 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  ingle connection
6730: 20 63 61 6e 20 68 6f 6c 64 20 61 20 72 65 73 65   can hold a rese
6740: 72 76 65 64 20 6c 6f 63 6b 0a 20 20 61 74 20 61  rved lock.  at a
6750: 6e 79 20 70 6f 69 6e 74 20 69 6e 20 74 69 6d 65  ny point in time
6760: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4c  .  The [SQLITE_L
6770: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 20 69 73 20  OCK_PENDING] is 
6780: 61 6c 73 6f 20 70 65 72 6d 69 73 73 69 6f 6e 20  also permission 
6790: 74 6f 0a 20 20 72 65 61 64 20 74 68 65 20 66 69  to.  read the fi
67a0: 6c 65 2e 20 20 4f 74 68 65 72 20 63 6f 6e 6e 65  le.  Other conne
67b0: 63 74 69 6f 6e 73 20 63 61 6e 20 63 6f 6e 74 69  ctions can conti
67c0: 6e 75 65 20 74 6f 20 72 65 61 64 20 74 68 65 20  nue to read the 
67d0: 66 69 6c 65 20 61 73 20 77 65 6c 6c 2c 0a 20 20  file as well,.  
67e0: 62 75 74 20 6e 6f 20 6f 74 68 65 72 20 63 6f 6e  but no other con
67f0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77  nection is allow
6800: 65 64 20 74 6f 20 65 73 63 61 6c 61 74 65 20 61  ed to escalate a
6810: 20 6c 6f 63 6b 20 66 72 6f 6d 20 6e 6f 6e 65 20   lock from none 
6820: 74 6f 20 73 68 61 72 65 64 2e 0a 20 20 5b 53 51  to shared..  [SQ
6830: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6840: 49 56 45 5d 20 69 73 20 70 65 72 6d 69 73 73 69  IVE] is permissi
6850: 6f 6e 20 74 6f 20 77 72 69 74 65 20 6f 6e 20 74  on to write on t
6860: 68 65 20 66 69 6c 65 2e 20 20 4f 6e 6c 79 20 61  he file.  Only a
6870: 20 73 69 6e 67 6c 65 0a 20 20 63 6f 6e 6e 65 63   single.  connec
6880: 74 69 6f 6e 20 63 61 6e 20 68 6f 6c 64 20 61 6e  tion can hold an
6890: 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 20   exclusive lock 
68a0: 61 6e 64 20 6e 6f 20 6f 74 68 65 72 20 63 6f 6e  and no other con
68b0: 6e 65 63 74 69 6f 6e 20 63 61 6e 20 68 6f 6c 64  nection can hold
68c0: 0a 20 20 61 6e 79 20 6c 6f 63 6b 20 28 6f 74 68  .  any lock (oth
68d0: 65 72 20 74 68 61 6e 20 22 6e 6f 6e 65 22 29 20  er than "none") 
68e0: 77 68 69 6c 65 20 6f 6e 65 20 63 6f 6e 6e 65 63  while one connec
68f0: 74 69 6f 6e 20 69 73 20 68 6f 6c 64 20 61 6e 20  tion is hold an 
6900: 65 78 63 6c 75 73 69 76 65 0a 20 20 6c 6f 63 6b  exclusive.  lock
6910: 2e 20 20 54 68 65 20 78 4c 6f 63 6b 20 72 65 74  .  The xLock ret
6920: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
6930: 20 6f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   on success, [SQ
6940: 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 69 74  LITE_BUSY] if it
6950: 0a 20 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  .  is unable to 
6960: 6f 62 74 61 69 6e 20 74 68 65 20 6c 6f 63 6b 2c  obtain the lock,
6970: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
6980: 52 5f 52 44 4c 4f 43 4b 5d 20 69 66 20 73 6f 6d  R_RDLOCK] if som
6990: 65 74 68 69 6e 67 20 65 6c 73 65 0a 20 20 67 6f  ething else.  go
69a0: 65 73 20 77 72 6f 6e 67 2e 20 20 54 68 65 20 78  es wrong.  The x
69b0: 55 6e 6c 6f 63 6b 20 6d 65 74 68 6f 64 20 72 65  Unlock method re
69c0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
69d0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
69e0: 0a 20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  .  [SQLITE_IOERR
69f0: 5f 55 4e 4c 4f 43 4b 5d 20 66 6f 72 20 70 72 6f  _UNLOCK] for pro
6a00: 62 6c 65 6d 73 2e 0a 7d 0a 0a 50 41 52 41 47 52  blems..}..PARAGR
6a10: 41 50 48 20 7b 0a 20 20 54 68 65 20 78 43 68 65  APH {.  The xChe
6a20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 20 6d  ckReservedLock m
6a30: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f 20  ethod checks to 
6a40: 73 65 65 20 69 66 20 61 6e 6f 74 68 65 72 20 63  see if another c
6a50: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 72 0a 20 20 61  onnection or.  a
6a60: 6e 6f 74 68 65 72 20 70 72 6f 63 65 73 73 20 69  nother process i
6a70: 73 20 63 75 72 72 65 6e 74 6c 79 20 68 6f 6c 64  s currently hold
6a80: 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 2c 20  ing a reserved, 
6a90: 70 65 6e 64 69 6e 67 2c 20 6f 72 20 65 78 63 6c  pending, or excl
6aa0: 75 73 69 76 65 0a 20 20 6c 6f 63 6b 20 6f 6e 20  usive.  lock on 
6ab0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
6ac0: 74 75 72 6e 73 20 74 72 75 65 20 6f 72 20 66 61  turns true or fa
6ad0: 6c 73 65 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50  lse..}..PARAGRAP
6ae0: 48 20 7b 0a 20 20 54 68 65 20 78 46 69 6c 65 43  H {.  The xFileC
6af0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6b00: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6b10: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6b20: 77 73 20 63 75 73 74 6f 6d 0a 20 20 56 46 53 20  ws custom.  VFS 
6b30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6b40: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6b50: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6b60: 20 75 73 69 6e 67 20 74 68 65 0a 20 20 28 6e 65   using the.  (ne
6b70: 77 20 61 6e 64 20 65 78 70 65 72 69 6d 65 6e 74  w and experiment
6b80: 61 6c 29 0a 20 20 5b 73 71 6c 69 74 65 33 5f 66  al).  [sqlite3_f
6b90: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6ba0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
6bb0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
6bc0: 65 6e 74 0a 20 20 69 73 20 61 6e 20 69 6e 74 65  ent.  is an inte
6bd0: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 20 54 68  ger opcode.   Th
6be0: 65 20 74 68 69 72 64 0a 20 20 61 72 67 75 6d 65  e third.  argume
6bf0: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
6c00: 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 69 73  pointer which is
6c10: 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
6c20: 61 20 70 6f 69 6e 74 65 72 0a 20 20 74 6f 20 61  a pointer.  to a
6c30: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
6c40: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
6c50: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
6c60: 6e 20 77 68 69 63 68 20 74 6f 0a 20 20 77 72 69  n which to.  wri
6c70: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
6c80: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
6c90: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
6ca0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 20 20  ol() might be.  
6cb0: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
6cc0: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
6cd0: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
6ce0: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
6cf0: 20 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65    locking strate
6d00: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
6d10: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
6d20: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
6d30: 72 65 0a 20 20 61 62 6f 75 74 20 74 68 65 20 73  re.  about the s
6d40: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6d50: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6d60: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6d70: 51 4c 69 74 65 0a 20 20 63 6f 72 65 20 72 65 73  QLite.  core res
6d80: 65 72 76 65 73 20 6f 70 63 6f 64 65 73 20 6c 65  erves opcodes le
6d90: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
6da0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 20 0a 20 20  its own use. .  
6db0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
6dc0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
6dd0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
6de0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
6df0: 61 69 6c 61 62 6c 65 2e 0a 20 20 41 70 70 6c 69  ailable..  Appli
6e00: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
6e10: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
6e20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6e30: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
6e40: 64 65 73 20 0a 20 20 67 72 65 61 74 65 72 20 74  des .  greater t
6e50: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
6e60: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 7d 0a 0a 50   conflicts..}..P
6e70: 41 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68 65  ARAGRAPH {.  The
6e80: 20 78 53 65 63 74 6f 72 53 69 7a 65 20 72 65 74   xSectorSize ret
6e90: 75 72 6e 73 20 74 68 65 20 22 73 65 63 74 6f 72  urns the "sector
6ea0: 20 73 69 7a 65 22 20 6f 66 20 74 68 65 20 75 6e   size" of the un
6eb0: 64 65 72 6c 79 69 6e 67 0a 20 20 6e 6f 6e 2d 76  derlying.  non-v
6ec0: 6f 6c 61 74 69 6c 65 20 6d 65 64 69 61 2e 20 20  olatile media.  
6ed0: 41 20 22 73 65 63 74 6f 72 22 20 69 73 20 64 65  A "sector" is de
6ee0: 66 69 6e 65 64 20 61 73 20 74 68 65 20 73 6d 61  fined as the sma
6ef0: 6c 6c 65 73 74 20 75 6e 69 74 20 6f 66 0a 20 20  llest unit of.  
6f00: 73 74 6f 72 61 67 65 20 74 68 61 74 20 63 61 6e  storage that can
6f10: 20 62 65 20 77 72 69 74 74 65 6e 20 77 69 74 68   be written with
6f20: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 20 61  out disturbing a
6f30: 64 6a 61 63 65 6e 74 20 73 74 6f 72 61 67 65 2e  djacent storage.
6f40: 0a 20 20 4f 6e 20 61 20 64 69 73 6b 20 64 72 69  .  On a disk dri
6f50: 76 65 20 74 68 65 20 22 73 65 63 74 6f 72 20 73  ve the "sector s
6f60: 69 7a 65 22 20 68 61 73 20 75 6e 74 69 6c 20 72  ize" has until r
6f70: 65 63 65 6e 74 6c 79 20 62 65 65 6e 20 35 31 32  ecently been 512
6f80: 20 62 79 74 65 73 2c 0a 20 20 74 68 6f 75 67 68   bytes,.  though
6f90: 20 74 68 65 72 65 20 69 73 20 61 20 70 75 73 68   there is a push
6fa0: 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 69   to increase thi
6fb0: 73 20 76 61 6c 75 65 20 74 6f 20 34 4b 69 42 2e  s value to 4KiB.
6fc0: 20 20 53 51 4c 69 74 65 20 6e 65 65 64 73 0a 20    SQLite needs. 
6fd0: 20 74 6f 20 6b 6e 6f 77 20 74 68 65 20 73 65 63   to know the sec
6fe0: 74 6f 72 20 73 69 7a 65 20 73 6f 20 74 68 61 74  tor size so that
6ff0: 20 69 74 20 63 61 6e 20 77 72 69 74 65 20 61 20   it can write a 
7000: 66 75 6c 6c 20 73 65 63 74 6f 72 20 61 74 20 61  full sector at a
7010: 0a 20 20 74 69 6d 65 2c 20 61 6e 64 20 74 68 75  .  time, and thu
7020: 73 20 61 76 6f 69 64 20 63 6f 72 72 75 70 74 69  s avoid corrupti
7030: 6e 67 20 61 64 6a 61 63 65 6e 74 20 73 74 6f 72  ng adjacent stor
7040: 61 67 65 20 73 70 61 63 65 20 69 66 20 61 20 70  age space if a p
7050: 6f 77 65 72 0a 20 20 6c 6f 73 65 20 6f 63 63 75  ower.  lose occu
7060: 72 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  rs in the middle
7070: 20 6f 66 20 61 20 77 72 69 74 65 2e 0a 7d 0a 0a   of a write..}..
7080: 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68  PARAGRAPH {.  Th
7090: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
70a0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
70b0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
70c0: 65 72 20 62 69 74 20 76 65 63 74 6f 72 20 74 68  er bit vector th
70d0: 61 74 0a 20 20 64 65 66 69 6e 65 73 20 61 6e 79  at.  defines any
70e0: 20 73 70 65 63 69 61 6c 20 70 72 6f 70 65 72 74   special propert
70f0: 69 65 73 20 74 68 61 74 20 74 68 65 20 75 6e 64  ies that the und
7100: 65 72 6c 79 69 6e 67 20 73 74 6f 72 61 67 65 20  erlying storage 
7110: 6d 65 64 69 75 6d 20 6d 69 67 68 74 0a 20 20 68  medium might.  h
7120: 61 76 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ave that SQLite 
7130: 63 61 6e 20 75 73 65 20 74 6f 20 69 6e 63 72 65  can use to incre
7140: 61 73 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 2e  ase performance.
7150: 20 20 54 68 65 20 61 6c 6c 6f 77 65 64 20 72 65    The allowed re
7160: 74 75 72 6e 0a 20 20 69 73 20 74 68 65 20 62 69  turn.  is the bi
7170: 74 2d 77 69 73 65 20 4f 52 20 6f 66 20 74 68 65  t-wise OR of the
7180: 20 66 6f 6c 6c 6f 77 69 6e 67 20 76 61 6c 75 65   following value
7190: 73 3a 0a 20 20 3c 75 6c 3e 0a 20 20 3c 6c 69 3e  s:.  <ul>.  <li>
71a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
71b0: 54 4f 4d 49 43 5d 0a 20 20 3c 6c 69 3e 20 5b 53  TOMIC].  <li> [S
71c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71d0: 49 43 35 31 32 5d 0a 20 20 3c 6c 69 3e 20 5b 53  IC512].  <li> [S
71e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71f0: 49 43 31 4b 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51  IC1K].  <li> [SQ
7200: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7210: 43 32 4b 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51 4c  C2K].  <li> [SQL
7220: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7230: 34 4b 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51 4c 49  4K].  <li> [SQLI
7240: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
7250: 4b 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  K].  <li> [SQLIT
7260: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
7270: 4b 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  K].  <li> [SQLIT
7280: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
7290: 4b 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  K].  <li> [SQLIT
72a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
72b0: 4b 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  K].  <li> [SQLIT
72c0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
72d0: 45 4e 44 5d 0a 20 20 3c 6c 69 3e 20 5b 53 51 4c  END].  <li> [SQL
72e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
72f0: 54 49 41 4c 5d 0a 20 20 3c 2f 75 6c 3e 0a 20 20  TIAL].  </ul>.  
7300: 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  The [SQLITE_IOCA
7310: 50 5f 41 54 4f 4d 49 43 5d 20 62 69 74 20 6d 65  P_ATOMIC] bit me
7320: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7330: 74 65 73 20 74 6f 20 74 68 69 73 20 64 65 76 69  tes to this devi
7340: 63 65 20 61 72 65 0a 20 20 61 74 6f 6d 69 63 20  ce are.  atomic 
7350: 69 6e 20 74 68 65 20 73 65 6e 73 65 20 74 68 61  in the sense tha
7360: 74 20 65 69 74 68 65 72 20 74 68 65 20 65 6e 74  t either the ent
7370: 69 72 65 20 77 72 69 74 65 20 6f 63 63 75 72 73  ire write occurs
7380: 20 6f 72 20 6e 6f 6e 65 20 6f 66 20 69 74 0a 20   or none of it. 
7390: 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 74   occurs.  The ot
73a0: 68 65 72 20 0a 20 20 5b 53 51 4c 49 54 45 5f 49  her .  [SQLITE_I
73b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 7c 20 53 51  OCAP_ATOMIC | SQ
73c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73d0: 43 3c 69 3e 6e 6e 6e 3c 2f 69 3e 5d 20 76 61 6c  C<i>nnn</i>] val
73e0: 75 65 73 20 69 6e 64 69 63 61 74 65 20 74 68 61  ues indicate tha
73f0: 74 0a 20 20 77 72 69 74 65 73 20 6f 66 20 61 6c  t.  writes of al
7400: 69 67 6e 65 64 20 62 6c 6f 63 6b 73 20 6f 66 20  igned blocks of 
7410: 74 68 65 20 69 6e 64 69 63 61 74 65 64 20 73 69  the indicated si
7420: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 0a 20  ze are atomic.. 
7430: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7440: 41 46 45 5f 41 50 50 45 4e 44 5d 20 6d 65 61 6e  AFE_APPEND] mean
7450: 73 20 74 68 61 74 20 77 68 65 6e 20 65 78 74 65  s that when exte
7460: 6e 64 69 6e 67 20 61 20 66 69 6c 65 20 77 69 74  nding a file wit
7470: 68 20 6e 65 77 0a 20 20 64 61 74 61 2c 20 74 68  h new.  data, th
7480: 65 20 6e 65 77 20 64 61 74 61 20 69 73 20 77 72  e new data is wr
7490: 69 74 74 65 6e 20 66 69 72 73 74 20 61 6e 64 20  itten first and 
74a0: 74 68 65 6e 20 74 68 65 20 66 69 6c 65 20 73 69  then the file si
74b0: 7a 65 20 69 73 20 75 70 64 61 74 65 64 2e 0a 20  ze is updated.. 
74c0: 20 53 6f 20 69 66 20 61 20 70 6f 77 65 72 20 66   So if a power f
74d0: 61 69 6c 75 72 65 20 6f 63 63 75 72 73 2c 20 74  ailure occurs, t
74e0: 68 65 72 65 20 69 73 20 6e 6f 20 63 68 61 6e 63  here is no chanc
74f0: 65 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20  e that the file 
7500: 6d 69 67 68 74 20 68 61 76 65 0a 20 20 62 65 65  might have.  bee
7510: 6e 20 65 78 74 65 6e 64 65 64 20 77 69 74 68 20  n extended with 
7520: 72 61 6e 64 6f 6d 6e 65 73 73 2e 20 20 54 68 65  randomness.  The
7530: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7540: 45 51 55 45 4e 54 49 41 4c 5d 20 62 69 74 20 6d  EQUENTIAL] bit m
7550: 65 61 6e 73 0a 20 20 74 68 61 74 20 61 6c 6c 20  eans.  that all 
7560: 77 72 69 74 65 73 20 6f 63 63 75 72 20 69 6e 20  writes occur in 
7570: 74 68 65 20 6f 72 64 65 72 20 74 68 61 74 20 74  the order that t
7580: 68 65 79 20 61 72 65 20 69 73 73 75 65 64 20 61  hey are issued a
7590: 6e 64 20 61 72 65 20 6e 6f 74 0a 20 20 72 65 6f  nd are not.  reo
75a0: 72 64 65 72 65 64 20 62 79 20 74 68 65 20 75 6e  rdered by the un
75b0: 64 65 72 6c 79 69 6e 67 20 66 69 6c 65 20 73 79  derlying file sy
75c0: 73 74 65 6d 2e 0a 7d 0a 0a 48 45 41 44 49 4e 47  stem..}..HEADING
75d0: 20 33 20 7b 43 68 65 63 6b 6c 69 73 74 20 46 6f   3 {Checklist Fo
75e0: 72 20 43 6f 6e 73 74 72 75 63 74 69 6e 67 20 41  r Constructing A
75f0: 20 4e 65 77 20 56 46 53 7d 0a 0a 50 41 52 41 47   New VFS}..PARAG
7600: 52 41 50 48 20 7b 0a 20 20 54 68 65 20 70 72 65  RAPH {.  The pre
7610: 63 65 64 69 6e 67 20 70 61 72 61 67 72 61 70 68  ceding paragraph
7620: 73 20 63 6f 6e 74 61 69 6e 20 61 20 6c 6f 74 20  s contain a lot 
7630: 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  of information..
7640: 20 20 54 6f 20 65 61 73 65 20 74 68 65 20 74 61    To ease the ta
7650: 73 6b 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 69  sk of constructi
7660: 6e 67 0a 20 20 61 20 6e 65 77 20 56 46 53 20 66  ng.  a new VFS f
7670: 6f 72 20 53 51 4c 69 74 65 20 77 65 20 6f 66 66  or SQLite we off
7680: 65 72 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  er the following
7690: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
76a0: 63 68 65 63 6b 6c 69 73 74 3a 0a 7d 0a 0a 50 41  checklist:.}..PA
76b0: 52 41 47 52 41 50 48 20 7b 0a 20 20 3c 6f 6c 3e  RAGRAPH {.  <ol>
76c0: 0a 20 20 3c 6c 69 3e 20 44 65 66 69 6e 65 20 61  .  <li> Define a
76d0: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 73 75  n appropriate su
76e0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 20 5b 73  bclass of the [s
76f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7700: 65 63 74 2e 0a 20 20 3c 6c 69 3e 20 49 6d 70 6c  ect..  <li> Impl
7710: 65 6d 65 6e 74 20 74 68 65 20 6d 65 74 68 6f 64  ement the method
7720: 73 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68  s required by th
7730: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7740: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 20  thods] object.. 
7750: 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 61 20 73   <li> Create a s
7760: 74 61 74 69 63 20 61 6e 64 20 0a 20 20 20 20 20  tatic and .     
7770: 20 20 63 6f 6e 73 74 61 6e 74 20 5b 73 71 6c 69    constant [sqli
7780: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7790: 6f 62 6a 65 63 74 20 63 6f 6e 74 61 69 6e 69 6e  object containin
77a0: 67 20 70 6f 69 6e 74 65 72 73 0a 20 20 20 20 20  g pointers.     
77b0: 20 20 74 6f 20 74 68 65 20 6d 65 74 68 6f 64 73    to the methods
77c0: 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
77d0: 75 73 20 73 74 65 70 2e 0a 20 20 3c 6c 69 3e 20  us step..  <li> 
77e0: 49 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 78 4f  Implement the xO
77f0: 70 65 6e 20 6d 65 74 68 6f 64 20 74 68 61 74 20  pen method that 
7800: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 61 6e 64  opens a file and
7810: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 20 20   populates an.  
7820: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 69       [sqlite3_fi
7830: 6c 65 5d 20 6f 62 6a 65 63 74 2c 20 69 6e 63 6c  le] object, incl
7840: 75 64 69 6e 67 20 73 65 74 74 69 6e 67 20 70 4d  uding setting pM
7850: 65 74 68 6f 64 73 20 74 6f 0a 20 20 20 20 20 20  ethods to.      
7860: 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 5b 73   point to the [s
7870: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7880: 73 5d 20 6f 62 6a 65 63 74 20 66 72 6f 6d 20 74  s] object from t
7890: 68 65 20 70 72 65 76 69 6f 75 73 20 73 74 65 70  he previous step
78a0: 2e 0a 20 20 3c 6c 69 3e 20 49 6d 70 6c 65 6d 65  ..  <li> Impleme
78b0: 6e 74 20 74 68 65 20 6f 74 68 65 72 20 6d 65 74  nt the other met
78c0: 68 6f 64 73 20 72 65 71 75 69 72 65 64 20 62 79  hods required by
78d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 2e 0a   [sqlite3_vfs]..
78e0: 20 20 3c 6c 69 3e 20 44 65 66 69 6e 65 20 61 20    <li> Define a 
78f0: 73 74 61 74 69 63 20 28 62 75 74 20 6e 6f 74 20  static (but not 
7900: 63 6f 6e 73 74 61 6e 74 29 20 5b 73 71 6c 69 74  constant) [sqlit
7910: 65 33 5f 76 66 73 5d 20 73 74 72 75 63 74 75 72  e3_vfs] structur
7920: 65 20 74 68 61 74 0a 20 20 20 20 20 20 20 63 6f  e that.       co
7930: 6e 74 61 69 6e 73 20 70 6f 69 6e 74 65 72 73 20  ntains pointers 
7940: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
7950: 68 6f 64 20 61 6e 64 20 74 68 65 20 6f 74 68 65  hod and the othe
7960: 72 20 6d 65 74 68 6f 64 73 20 61 6e 64 0a 20 20  r methods and.  
7970: 20 20 20 20 20 77 68 69 63 68 20 63 6f 6e 74 61       which conta
7980: 69 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  ins the appropri
7990: 61 74 65 20 76 61 6c 75 65 73 20 66 6f 72 20 69  ate values for i
79a0: 56 65 72 73 69 6f 6e 2c 20 73 7a 4f 73 46 69 6c  Version, szOsFil
79b0: 65 2c 0a 20 20 20 20 20 20 20 6d 78 50 61 74 68  e,.       mxPath
79c0: 6e 61 6d 65 2c 20 7a 4e 61 6d 65 2c 20 61 6e 64  name, zName, and
79d0: 20 70 41 70 70 44 61 74 61 2e 0a 20 20 3c 6c 69   pAppData..  <li
79e0: 3e 20 49 6d 70 6c 65 6d 65 6e 74 20 61 20 70 72  > Implement a pr
79f0: 6f 63 65 64 75 72 65 20 74 68 61 74 20 63 61 6c  ocedure that cal
7a00: 6c 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  ls [sqlite3_vfs_
7a10: 72 65 67 69 73 74 65 72 28 29 5d 20 61 6e 64 0a  register()] and.
7a20: 20 20 20 20 20 20 20 70 61 73 73 65 73 20 69 74         passes it
7a30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
7a40: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
7a50: 73 74 72 75 63 74 75 72 65 20 66 72 6f 6d 20 74  structure from t
7a60: 68 65 20 70 72 65 76 69 6f 75 73 0a 20 20 20 20  he previous.    
7a70: 20 20 20 73 74 65 70 2e 20 20 54 68 69 73 20 70     step.  This p
7a80: 72 6f 63 65 64 75 72 65 20 69 73 20 70 72 6f 62  rocedure is prob
7a90: 61 62 6c 79 20 74 68 65 20 6f 6e 6c 79 20 65 78  ably the only ex
7aa0: 70 6f 72 74 65 64 20 73 79 6d 62 6f 6c 20 69 6e  ported symbol in
7ab0: 20 74 68 65 0a 20 20 20 20 20 20 20 73 6f 75 72   the.       sour
7ac0: 63 65 20 66 69 6c 65 20 74 68 61 74 20 69 6d 70  ce file that imp
7ad0: 6c 65 6d 65 6e 74 73 20 79 6f 75 72 20 56 46 53  lements your VFS
7ae0: 2e 0a 20 20 3c 2f 6f 6c 3e 0a 7d 0a 0a 50 41 52  ..  </ol>.}..PAR
7af0: 41 47 52 41 50 48 20 7b 0a 20 20 57 69 74 68 69  AGRAPH {.  Withi
7b00: 6e 20 79 6f 75 72 20 61 70 70 6c 69 63 61 74 69  n your applicati
7b10: 6f 6e 2c 20 63 61 6c 6c 20 74 68 65 20 70 72 6f  on, call the pro
7b20: 63 65 64 75 72 65 20 69 6d 70 6c 65 6d 65 6e 74  cedure implement
7b30: 65 64 20 69 6e 20 74 68 65 20 6c 61 73 74 0a 20  ed in the last. 
7b40: 20 73 74 65 70 20 61 62 6f 76 65 20 61 73 20 70   step above as p
7b50: 61 72 74 20 6f 66 20 79 6f 75 72 20 69 6e 69 74  art of your init
7b60: 69 61 6c 69 7a 61 74 69 6f 6e 20 70 72 6f 63 65  ialization proce
7b70: 73 73 20 62 65 66 6f 72 65 20 61 6e 79 0a 20 20  ss before any.  
7b80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7b90: 69 6f 6e 73 20 61 72 65 20 6f 70 65 6e 65 64 2e  ions are opened.
7ba0: 20 20 0a 7d 0a 0a 48 45 41 44 49 4e 47 20 31 20    .}..HEADING 1 
7bb0: 7b 54 68 65 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  {The Memory Allo
7bc0: 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
7bd0: 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20  }..PARAGRAPH {. 
7be0: 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
7bf0: 76 65 72 73 69 6f 6e 20 33 2e 35 2c 20 53 51 4c  version 3.5, SQL
7c00: 69 74 65 20 6f 62 74 61 69 6e 73 20 61 6c 6c 20  ite obtains all 
7c10: 6f 66 20 74 68 65 20 68 65 61 70 20 6d 65 6d 6f  of the heap memo
7c20: 72 79 20 69 74 0a 20 20 6e 65 65 64 73 20 75 73  ry it.  needs us
7c30: 69 6e 67 20 74 68 65 20 72 6f 75 74 69 6e 65 73  ing the routines
7c40: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
7c50: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
7c60: 65 65 28 29 5d 2c 20 61 6e 64 0a 20 20 5b 73 71  ee()], and.  [sq
7c70: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
7c80: 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
7c90: 73 20 68 61 76 65 20 65 78 69 73 74 65 64 20 69  s have existed i
7ca0: 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
7cb0: 0a 20 20 6f 66 20 53 51 4c 69 74 65 2c 20 62 75  .  of SQLite, bu
7cc0: 74 20 53 51 4c 69 74 65 20 68 61 73 20 70 72 65  t SQLite has pre
7cd0: 76 69 6f 75 73 6c 79 20 62 79 70 61 73 73 65 64  viously bypassed
7ce0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
7cf0: 61 6e 64 20 75 73 65 64 0a 20 20 69 74 73 20 6f  and used.  its o
7d00: 77 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  wn memory alloca
7d10: 74 6f 72 2e 20 20 54 68 69 73 20 61 6c 6c 20 63  tor.  This all c
7d20: 68 61 6e 67 65 73 20 69 6e 20 76 65 72 73 69 6f  hanges in versio
7d30: 6e 20 33 2e 35 2e 30 2e 0a 7d 0a 0a 50 41 52 41  n 3.5.0..}..PARA
7d40: 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20 53 51  GRAPH {.  The SQ
7d50: 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65  Lite source tree
7d60: 20 61 63 74 75 61 6c 6c 79 20 63 6f 6e 74 61 69   actually contai
7d70: 6e 73 20 6d 75 6c 74 69 70 6c 65 20 76 65 72 73  ns multiple vers
7d80: 69 6f 6e 73 20 6f 66 20 74 68 65 0a 20 20 6d 65  ions of the.  me
7d90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
7da0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 68 69 67   The default hig
7db0: 68 2d 73 70 65 65 64 20 76 65 72 73 69 6f 6e 20  h-speed version 
7dc0: 66 6f 75 6e 64 20 69 6e 20 74 68 65 0a 20 20 22  found in the.  "
7dd0: 6d 65 6d 31 2e 63 22 20 73 6f 75 72 63 65 20 66  mem1.c" source f
7de0: 69 6c 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ile is used for 
7df0: 6d 6f 73 74 20 62 75 69 6c 64 73 2e 20 20 42 75  most builds.  Bu
7e00: 74 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  t if the SQLITE_
7e10: 4d 45 4d 44 45 42 55 47 0a 20 20 66 6c 61 67 20  MEMDEBUG.  flag 
7e20: 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 20 73 65  is enabled, a se
7e30: 70 61 72 61 74 65 20 6d 65 6d 6f 72 79 20 61 6c  parate memory al
7e40: 6c 6f 63 61 74 6f 72 20 74 68 65 20 22 6d 65 6d  locator the "mem
7e50: 32 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  2.c" source file
7e60: 0a 20 20 69 73 20 75 73 65 64 20 69 6e 73 74 65  .  is used inste
7e70: 61 64 2e 20 20 54 68 65 20 6d 65 6d 32 2e 63 20  ad.  The mem2.c 
7e80: 61 6c 6c 6f 63 61 74 6f 72 20 69 6d 70 6c 65 6d  allocator implem
7e90: 65 6e 74 73 20 6c 6f 74 73 20 6f 66 20 68 6f 6f  ents lots of hoo
7ea0: 6b 73 20 74 6f 0a 20 20 64 6f 20 65 72 72 6f 72  ks to.  do error
7eb0: 20 63 68 65 63 6b 69 6e 67 20 61 6e 64 20 74 6f   checking and to
7ec0: 20 73 69 6d 75 6c 61 74 65 20 6d 65 6d 6f 72 79   simulate memory
7ed0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
7ee0: 75 72 65 73 20 66 6f 72 20 74 65 73 74 69 6e 67  ures for testing
7ef0: 0a 20 20 70 75 72 70 6f 73 65 73 2e 20 20 42 6f  .  purposes.  Bo
7f00: 74 68 20 6f 66 20 74 68 65 73 65 20 61 6c 6c 6f  th of these allo
7f10: 63 61 74 6f 72 73 20 75 73 65 20 74 68 65 20 6d  cators use the m
7f20: 61 6c 6c 6f 63 28 29 2f 66 72 65 65 28 29 20 69  alloc()/free() i
7f30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 20 20  mplementation.  
7f40: 69 6e 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  in the standard 
7f50: 43 20 6c 69 62 72 61 72 79 2e 0a 7d 0a 0a 50 41  C library..}..PA
7f60: 52 41 47 52 41 50 48 20 7b 0a 20 20 41 70 70 6c  RAGRAPH {.  Appl
7f70: 69 63 61 74 69 6f 6e 73 20 61 72 65 20 6e 6f 74  ications are not
7f80: 20 72 65 71 75 69 72 65 64 20 74 6f 20 75 73 65   required to use
7f90: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
7fa0: 20 73 74 61 6e 64 61 72 64 20 6d 65 6d 6f 72 79   standard memory
7fb0: 0a 20 20 61 6c 6c 6f 63 61 74 6f 72 73 2e 20 20  .  allocators.  
7fc0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
7fd0: 70 69 6c 65 64 20 77 69 74 68 20 5b 6f 6d 69 74  piled with [omit
7fe0: 66 65 61 74 75 72 65 73 20 7c 20 53 51 4c 49 54  features | SQLIT
7ff0: 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
8000: 4c 4f 43 41 54 49 4f 4e 5d 0a 20 20 74 68 65 6e  LOCATION].  then
8010: 20 6e 6f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   no implementati
8020: 6f 6e 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  on for the [sqli
8030: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
8040: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
8050: 29 5d 2c 0a 20 20 61 6e 64 20 5b 73 71 6c 69 74  )],.  and [sqlit
8060: 65 33 5f 66 72 65 65 28 29 5d 20 66 75 6e 63 74  e3_free()] funct
8070: 69 6f 6e 73 20 69 73 20 70 72 6f 76 69 64 65 64  ions is provided
8080: 2e 20 20 49 6e 73 74 65 61 64 2c 20 74 68 65 20  .  Instead, the 
8090: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 20 20 74 68  application.  th
80a0: 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
80b0: 20 53 51 4c 69 74 65 20 6d 75 73 74 20 70 72 6f   SQLite must pro
80c0: 76 69 64 65 20 69 74 73 20 6f 77 6e 20 69 6d 70  vide its own imp
80d0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
80e0: 68 65 73 65 0a 20 20 66 75 6e 63 74 69 6f 6e 73  hese.  functions
80f0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
8100: 6f 6e 20 70 72 6f 76 69 64 65 64 20 6d 65 6d 6f  on provided memo
8110: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ry allocator is 
8120: 6e 6f 74 20 72 65 71 75 69 72 65 64 0a 20 20 74  not required.  t
8130: 6f 20 75 73 65 20 74 68 65 20 6d 61 6c 6c 6f 63  o use the malloc
8140: 28 29 2f 66 72 65 65 28 29 20 69 6d 70 6c 65 6d  ()/free() implem
8150: 65 6e 74 61 74 69 6f 6e 20 69 6e 20 74 68 65 20  entation in the 
8160: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
8170: 72 79 2e 0a 20 20 41 6e 20 65 6d 62 65 64 64 65  ry..  An embedde
8180: 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  d application mi
8190: 67 68 74 20 70 72 6f 76 69 64 65 20 61 6e 20 61  ght provide an a
81a0: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
81b0: 79 20 61 6c 6c 6f 63 61 74 6f 72 0a 20 20 74 68  y allocator.  th
81c0: 61 74 20 75 73 65 73 20 6d 65 6d 6f 72 79 20 66  at uses memory f
81d0: 6f 72 20 61 20 66 69 78 65 64 20 6d 65 6d 6f 72  or a fixed memor
81e0: 79 20 70 6f 6f 6c 20 73 65 74 20 61 73 69 64 65  y pool set aside
81f0: 20 66 6f 72 20 74 68 65 20 65 78 63 6c 75 73 69   for the exclusi
8200: 76 65 0a 20 20 75 73 65 20 6f 66 20 53 51 4c 69  ve.  use of SQLi
8210: 74 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  te, for example.
8220: 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a  .}..PARAGRAPH {.
8230: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
8240: 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
8250: 65 69 72 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 61  eir own memory a
8260: 6c 6c 6f 63 61 74 6f 72 20 6d 75 73 74 20 70 72  llocator must pr
8270: 6f 76 69 64 65 0a 20 20 69 6d 70 6c 65 6d 65 6e  ovide.  implemen
8280: 74 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 75  tation for the u
8290: 73 75 61 6c 20 74 68 72 65 65 20 61 6c 6c 6f 63  sual three alloc
82a0: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
82b0: 0a 20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .  [sqlite3_mall
82c0: 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
82d0: 72 65 61 6c 6c 6f 63 28 29 5d 2c 20 61 6e 64 20  realloc()], and 
82e0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
82f0: 2e 0a 20 20 41 6e 64 20 74 68 65 79 20 6d 75 73  ..  And they mus
8300: 74 20 61 6c 73 6f 20 69 6d 70 6c 65 6d 65 6e 74  t also implement
8310: 20 61 20 66 6f 75 72 74 68 20 66 75 6e 63 74 69   a fourth functi
8320: 6f 6e 3a 0a 7d 0a 0a 43 4f 44 45 20 7b 0a 69 6e  on:.}..CODE {.in
8330: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
8340: 5f 61 6c 61 72 6d 28 0a 20 20 76 6f 69 64 28 2a  _alarm(.  void(*
8350: 78 43 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 20  xCallback)(void 
8360: 2a 70 41 72 67 2c 20 73 71 6c 69 74 65 33 5f 69  *pArg, sqlite3_i
8370: 6e 74 36 34 20 75 73 65 64 2c 20 69 6e 74 20 4e  nt64 used, int N
8380: 29 2c 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  ),.  void *pArg,
8390: 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  .  sqlite3_int64
83a0: 20 69 54 68 72 65 73 68 6f 6c 64 0a 29 3b 0a 7d   iThreshold.);.}
83b0: 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 54  ..PARAGRAPH {. T
83c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
83d0: 72 79 5f 61 6c 61 72 6d 5d 20 72 6f 75 74 69 6e  ry_alarm] routin
83e0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 67  e is used to reg
83f0: 69 73 74 65 72 0a 20 61 20 63 61 6c 6c 62 61 63  ister. a callbac
8400: 6b 20 6f 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  k on memory allo
8410: 63 61 74 69 6f 6e 20 65 76 65 6e 74 73 2e 0a 20  cation events.. 
8420: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
8430: 69 73 74 65 72 73 20 6f 72 20 63 6c 65 61 72 73  isters or clears
8440: 20 61 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61   a callbacks tha
8450: 74 20 66 69 72 65 73 20 77 68 65 6e 0a 20 74 68  t fires when. th
8460: 65 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  e amount of memo
8470: 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 65 78 63  ry allocated exc
8480: 65 65 64 73 20 69 54 68 72 65 73 68 6f 6c 64 2e  eeds iThreshold.
8490: 20 20 4f 6e 6c 79 0a 20 61 20 73 69 6e 67 6c 65    Only. a single
84a0: 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 62 65   callback can be
84b0: 20 72 65 67 69 73 74 65 72 65 64 20 61 74 20 61   registered at a
84c0: 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
84d0: 6c 0a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  l. to [sqlite3_m
84e0: 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 29 5d 20 6f  emory_alarm()] o
84f0: 76 65 72 77 72 69 74 65 73 20 74 68 65 20 70 72  verwrites the pr
8500: 65 76 69 6f 75 73 20 63 61 6c 6c 62 61 63 6b 2e  evious callback.
8510: 0a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
8520: 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  s disabled by se
8530: 74 74 69 6e 67 20 78 43 61 6c 6c 62 61 63 6b 20  tting xCallback 
8540: 74 6f 20 61 20 4e 55 4c 4c 0a 20 70 6f 69 6e 74  to a NULL. point
8550: 65 72 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48  er..}..PARAGRAPH
8560: 20 7b 0a 20 54 68 65 20 70 61 72 61 6d 65 74 65   {. The paramete
8570: 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
8580: 63 6b 20 61 72 65 20 74 68 65 20 70 41 72 67 20  ck are the pArg 
8590: 76 61 6c 75 65 2c 20 74 68 65 20 0a 20 61 6d 6f  value, the . amo
85a0: 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  unt of memory cu
85b0: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2c 20  rrently in use, 
85c0: 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  and the size of 
85d0: 74 68 65 0a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  the. allocation 
85e0: 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
85f0: 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  e callback.  The
8600: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a 20   callback will. 
8610: 70 72 65 73 75 6d 61 62 6c 79 20 69 6e 76 6f 6b  presumably invok
8620: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
8630: 29 5d 20 74 6f 20 66 72 65 65 20 75 70 20 6d 65  )] to free up me
8640: 6d 6f 72 79 20 73 70 61 63 65 2e 0a 20 54 68 65  mory space.. The
8650: 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 69 6e   callback may in
8660: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61  voke [sqlite3_ma
8670: 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
8680: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 20  te3_realloc()]. 
8690: 62 75 74 20 69 66 20 69 74 20 64 6f 65 73 2c 20  but if it does, 
86a0: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61  no additional ca
86b0: 6c 6c 62 61 63 6b 73 20 77 69 6c 6c 20 62 65 20  llbacks will be 
86c0: 69 6e 76 6f 6b 65 64 20 62 79 0a 20 74 68 65 20  invoked by. the 
86d0: 72 65 63 75 72 73 69 76 65 20 63 61 6c 6c 73 2e  recursive calls.
86e0: 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a  .}..PARAGRAPH {.
86f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   The [sqlite3_so
8700: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d  ft_heap_limit()]
8710: 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
8720: 20 62 79 20 72 65 67 69 73 74 65 72 69 6e 67 0a   by registering.
8730: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 61 72 6d 20   a memory alarm 
8740: 61 74 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  at the soft heap
8750: 20 6c 69 6d 69 74 20 61 6e 64 20 69 6e 76 6f 6b   limit and invok
8760: 69 6e 67 20 0a 20 5b 73 71 6c 69 74 65 33 5f 72  ing . [sqlite3_r
8770: 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
8780: 20 69 6e 20 74 68 65 20 61 6c 61 72 6d 20 63 61   in the alarm ca
8790: 6c 6c 62 61 63 6b 2e 20 20 41 70 70 6c 69 63 61  llback.  Applica
87a0: 74 69 6f 6e 0a 20 70 72 6f 67 72 61 6d 73 20 73  tion. programs s
87b0: 68 6f 75 6c 64 20 6e 6f 74 20 61 74 74 65 6d 70  hould not attemp
87c0: 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
87d0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
87e0: 72 6d 28 29 5d 0a 20 69 6e 74 65 72 66 61 63 65  rm()]. interface
87f0: 20 62 65 63 61 75 73 65 20 64 6f 69 6e 67 20 73   because doing s
8800: 6f 20 77 69 6c 6c 20 69 6e 74 65 72 66 65 72 65  o will interfere
8810: 20 77 69 74 68 20 74 68 65 0a 20 5b 73 71 6c 69   with the. [sqli
8820: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
8830: 6d 69 74 28 29 5d 20 6d 6f 64 75 6c 65 2e 20 20  mit()] module.  
8840: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  This interface i
8850: 73 20 65 78 70 6f 73 65 64 0a 20 6f 6e 6c 79 20  s exposed. only 
8860: 73 6f 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  so that applicat
8870: 69 6f 6e 73 20 63 61 6e 20 70 72 6f 76 69 64 65  ions can provide
8880: 20 74 68 65 69 72 20 6f 77 6e 0a 20 61 6c 74 65   their own. alte
8890: 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
88a0: 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
88b0: 53 51 4c 69 74 65 20 63 6f 72 65 20 69 73 0a 20  SQLite core is. 
88c0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 6f  compiled with [o
88d0: 6d 69 74 66 65 61 74 75 72 65 73 20 7c 20 53 51  mitfeatures | SQ
88e0: 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
88f0: 5f 41 4c 4c 4f 43 41 54 49 4f 4e 5d 2e 0a 7d 0a  _ALLOCATION]..}.
8900: 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 54  .PARAGRAPH {.  T
8910: 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
8920: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 69 6e  ry allocators in
8930: 20 53 51 4c 69 74 65 20 61 6c 73 6f 20 70 72 6f   SQLite also pro
8940: 76 69 64 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69  vide the followi
8950: 6e 67 0a 20 20 61 64 64 69 74 69 6f 6e 61 6c 20  ng.  additional 
8960: 69 6e 74 65 72 66 61 63 65 73 3a 0a 7d 0a 0a 43  interfaces:.}..C
8970: 4f 44 45 20 7b 0a 73 71 6c 69 74 65 33 5f 69 6e  ODE {.sqlite3_in
8980: 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
8990: 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
89a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
89b0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
89c0: 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
89d0: 6c 61 67 29 3b 0a 7d 0a 0a 50 41 52 41 47 52 41  lag);.}..PARAGRA
89e0: 50 48 20 7b 0a 20 20 54 68 65 73 65 20 69 6e 74  PH {.  These int
89f0: 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75  erfaces can be u
8a00: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
8a10: 61 74 69 6f 6e 20 74 6f 20 6d 6f 6e 69 74 6f 72  ation to monitor
8a20: 20 68 6f 77 0a 20 20 6d 75 63 68 20 6d 65 6d 6f   how.  much memo
8a30: 72 79 20 53 51 4c 69 74 65 20 69 73 20 75 73 69  ry SQLite is usi
8a40: 6e 67 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ng.  The [sqlite
8a50: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
8a60: 20 72 6f 75 74 69 6e 65 0a 20 20 72 65 74 75 72   routine.  retur
8a70: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
8a80: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
8a90: 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73   currently in us
8aa0: 65 20 61 6e 64 20 74 68 65 0a 20 20 5b 73 71 6c  e and the.  [sql
8ab0: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
8ac0: 77 61 74 65 72 28 29 5d 20 72 65 74 75 72 6e 73  water()] returns
8ad0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 73   the maximum ins
8ae0: 74 61 6e 74 61 6e 65 6f 75 73 0a 20 20 6d 65 6d  tantaneous.  mem
8af0: 6f 72 79 20 75 73 61 67 65 2e 20 20 4e 65 69 74  ory usage.  Neit
8b00: 68 65 72 20 72 6f 75 74 69 6e 65 20 69 6e 63 6c  her routine incl
8b10: 75 64 65 73 20 74 68 65 20 6f 76 65 72 68 65 61  udes the overhea
8b20: 64 20 61 73 73 6f 63 69 61 74 65 64 0a 20 20 77  d associated.  w
8b30: 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ith the memory a
8b40: 6c 6c 6f 63 61 74 6f 72 2e 20 20 54 68 65 73 65  llocator.  These
8b50: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 70 72   routines are pr
8b60: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 0a 20  ovided for use. 
8b70: 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
8b80: 69 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6e 65 76  ion.  SQLite nev
8b90: 65 72 20 69 6e 76 6f 6b 65 73 20 74 68 65 6d 20  er invokes them 
8ba0: 69 74 73 65 6c 66 2e 20 20 53 6f 20 69 66 0a 20  itself.  So if. 
8bb0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8bc0: 20 69 73 20 70 72 6f 76 69 64 69 6e 67 20 69 74   is providing it
8bd0: 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  s own memory all
8be0: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
8bf0: 6d 2c 0a 20 20 69 74 20 63 61 6e 20 6f 6d 69 74  m,.  it can omit
8c00: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
8c10: 73 20 69 66 20 64 65 73 69 72 65 64 2e 0a 7d 0a  s if desired..}.
8c20: 0a 48 45 41 44 49 4e 47 20 31 20 7b 54 68 65 20  .HEADING 1 {The 
8c30: 4d 75 74 65 78 20 53 75 62 73 79 73 74 65 6d 7d  Mutex Subsystem}
8c40: 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20  ..PARAGRAPH {.  
8c50: 53 51 4c 69 74 65 20 68 61 73 20 61 6c 77 61 79  SQLite has alway
8c60: 73 20 62 65 65 6e 20 74 68 72 65 61 64 73 61 66  s been threadsaf
8c70: 65 20 69 6e 20 74 68 65 20 73 65 6e 73 65 20 74  e in the sense t
8c80: 68 61 74 20 69 74 20 69 73 20 73 61 66 65 20 74  hat it is safe t
8c90: 6f 0a 20 20 75 73 65 20 64 69 66 66 65 72 65 6e  o.  use differen
8ca0: 74 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  t SQLite databas
8cb0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 6e  e connections in
8cc0: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
8cd0: 64 73 20 61 74 20 74 68 65 0a 20 20 73 61 6d 65  ds at the.  same
8ce0: 20 74 69 6d 65 2e 20 20 54 68 65 20 63 6f 6e 73   time.  The cons
8cf0: 74 72 61 69 6e 74 20 77 61 73 20 74 68 61 74 20  traint was that 
8d00: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
8d10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 20 20 63  e connection.  c
8d20: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
8d30: 20 69 6e 20 74 77 6f 20 73 65 70 61 72 61 74 65   in two separate
8d40: 20 74 68 72 65 61 64 73 20 61 74 20 6f 6e 63 65   threads at once
8d50: 2e 20 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  .  SQLite versio
8d60: 6e 20 33 2e 35 2e 30 0a 20 20 72 65 6c 61 78 65  n 3.5.0.  relaxe
8d70: 73 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  s this constrain
8d80: 74 2e 20 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48  t. .}..PARAGRAPH
8d90: 20 7b 0a 20 20 49 6e 20 6f 72 64 65 72 20 74 6f   {.  In order to
8da0: 20 61 6c 6c 6f 77 20 6d 75 6c 74 69 70 6c 65 20   allow multiple 
8db0: 74 68 72 65 61 64 73 20 74 6f 20 75 73 65 20 74  threads to use t
8dc0: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
8dd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 20 20 61 74   connection.  at
8de0: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2c 20   the same time, 
8df0: 53 51 4c 69 74 65 20 6d 75 73 74 20 6d 61 6b 65  SQLite must make
8e00: 20 65 78 74 65 6e 73 69 76 65 20 75 73 65 20 6f   extensive use o
8e10: 66 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20  f mutexes.  And 
8e20: 66 6f 72 0a 20 20 74 68 69 73 20 72 65 61 73 6f  for.  this reaso
8e30: 6e 20 61 20 6e 65 77 20 6d 75 74 65 78 20 73 75  n a new mutex su
8e40: 62 73 79 73 74 65 6d 20 61 73 20 62 65 65 6e 20  bsystem as been 
8e50: 61 64 64 65 64 2e 20 20 54 68 65 20 6d 75 74 65  added.  The mute
8e60: 78 20 73 75 62 73 79 73 74 65 6d 0a 20 20 61 73  x subsystem.  as
8e70: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
8e80: 6e 74 65 72 66 61 63 65 3a 0a 7d 0a 0a 43 4f 44  nterface:.}..COD
8e90: 45 20 7b 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  E {.sqlite3_mute
8ea0: 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
8eb0: 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
8ec0: 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
8ed0: 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
8ee0: 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
8ef0: 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
8f00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
8f10: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
8f20: 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
8f30: 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
8f40: 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
8f50: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
8f60: 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b 0a  .}..PARAGRAPH {.
8f70: 20 20 54 68 6f 75 67 68 20 74 68 65 73 65 20 72    Though these r
8f80: 6f 75 74 69 6e 65 73 20 65 78 69 73 74 20 66 6f  outines exist fo
8f90: 72 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  r the use of the
8fa0: 20 53 51 4c 69 74 65 20 63 6f 72 65 2c 20 0a 20   SQLite core, . 
8fb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8fc0: 65 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  e is free to use
8fd0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
8fe0: 61 73 20 77 65 6c 6c 2c 20 69 66 20 64 65 73 69  as well, if desi
8ff0: 72 65 64 2e 0a 20 20 41 20 6d 75 74 65 78 20 69  red..  A mutex i
9000: 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  s an [sqlite3_mu
9010: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  tex] object.  Th
9020: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
9030: 5f 61 6c 6c 6f 63 28 29 5d 0a 20 20 72 6f 75 74  _alloc()].  rout
9040: 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20  ine allocates a 
9050: 6e 65 77 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  new mutex object
9060: 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
9070: 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 0a 20 20  ointer to it..  
9080: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  The argument to 
9090: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
90a0: 6c 6c 6f 63 28 29 5d 20 73 68 6f 75 6c 64 20 62  lloc()] should b
90b0: 65 20 0a 20 20 5b 53 51 4c 49 54 45 5f 4d 55 54  e .  [SQLITE_MUT
90c0: 45 58 5f 46 41 53 54 5d 20 6f 72 20 5b 53 51 4c  EX_FAST] or [SQL
90d0: 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
90e0: 49 56 45 5d 20 66 6f 72 20 6e 6f 6e 2d 72 65 63  IVE] for non-rec
90f0: 75 72 73 69 76 65 0a 20 20 61 6e 64 20 72 65 63  ursive.  and rec
9100: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 2c 20  ursive mutexes, 
9110: 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 49  respectively.  I
9120: 66 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  f the underlying
9130: 20 73 79 73 74 65 6d 20 64 6f 65 73 0a 20 20 6e   system does.  n
9140: 6f 74 20 70 72 6f 76 69 64 65 20 6e 6f 6e 2d 72  ot provide non-r
9150: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
9160: 2c 20 74 68 65 6e 20 61 20 72 65 63 75 72 73 69  , then a recursi
9170: 76 65 20 6d 75 74 65 78 20 63 61 6e 20 62 65 0a  ve mutex can be.
9180: 20 20 73 75 62 73 74 69 74 75 74 65 64 20 69 6e    substituted in
9190: 20 74 68 61 74 20 63 61 73 65 2e 20 20 54 68 65   that case.  The
91a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
91b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
91c0: 63 28 29 5d 0a 20 20 63 61 6e 20 61 6c 73 6f 20  c()].  can also 
91d0: 62 65 20 61 20 63 6f 6e 73 74 61 6e 74 20 64 65  be a constant de
91e0: 73 69 67 6e 61 74 69 6e 67 20 6f 6e 65 20 6f 66  signating one of
91f0: 20 73 65 76 65 72 61 6c 20 73 74 61 74 69 63 20   several static 
9200: 6d 75 74 65 78 65 73 3a 0a 20 20 3c 75 6c 3e 0a  mutexes:.  <ul>.
9210: 20 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f    <li>  [SQLITE_
9220: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
9230: 54 45 52 5d 0a 20 20 3c 6c 69 3e 20 20 5b 53 51  TER].  <li>  [SQ
9240: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
9250: 43 5f 4d 45 4d 5d 0a 20 20 3c 6c 69 3e 20 20 5b  C_MEM].  <li>  [
9260: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
9270: 54 49 43 5f 4d 45 4d 32 5d 0a 20 20 3c 6c 69 3e  TIC_MEM2].  <li>
9280: 20 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f    [SQLITE_MUTEX_
9290: 53 54 41 54 49 43 5f 50 52 4e 47 5d 0a 20 20 3c  STATIC_PRNG].  <
92a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4d 55 54  li>  [SQLITE_MUT
92b0: 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 5d 0a 20  EX_STATIC_LRU]. 
92c0: 20 3c 2f 75 6c 3e 0a 20 20 54 68 65 73 65 20 73   </ul>.  These s
92d0: 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
92e0: 65 20 72 65 73 65 72 76 65 64 20 66 6f 72 20 75  e reserved for u
92f0: 73 65 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  se internally by
9300: 20 53 51 4c 69 74 65 0a 20 20 61 6e 64 20 73 68   SQLite.  and sh
9310: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
9320: 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
9330: 69 6f 6e 2e 20 20 54 68 65 20 73 74 61 74 69 63  ion.  The static
9340: 20 6d 75 74 65 78 65 73 0a 20 20 61 72 65 20 61   mutexes.  are a
9350: 6c 6c 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65  ll non-recursive
9360: 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20 7b  ..}..PARAGRAPH {
9370: 0a 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
9380: 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20 72 6f  mutex_free()] ro
9390: 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 20  utine should be 
93a0: 75 73 65 64 20 74 6f 20 64 65 61 6c 6c 6f 63 61  used to dealloca
93b0: 74 65 0a 20 20 61 20 6e 6f 6e 2d 73 74 61 74 69  te.  a non-stati
93c0: 63 20 6d 75 74 65 78 2e 20 20 49 66 20 61 20 73  c mutex.  If a s
93d0: 74 61 74 69 63 20 6d 75 74 65 78 20 69 73 20 70  tatic mutex is p
93e0: 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 72 6f  assed to this ro
93f0: 75 74 69 6e 65 0a 20 20 74 68 65 6e 20 74 68 65  utine.  then the
9400: 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
9410: 65 66 69 6e 65 64 2e 0a 7d 0a 0a 50 41 52 41 47  efined..}..PARAG
9420: 52 41 50 48 20 7b 0a 20 20 54 68 65 20 5b 73 71  RAPH {.  The [sq
9430: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
9440: 72 28 29 5d 20 61 74 74 65 6d 70 74 73 20 74 6f  r()] attempts to
9450: 20 65 6e 74 65 72 20 74 68 65 20 6d 75 74 65 78   enter the mutex
9460: 20 61 6e 64 20 62 6c 6f 63 6b 73 0a 20 20 69 66   and blocks.  if
9470: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 73   another threads
9480: 20 69 73 20 61 6c 72 65 61 64 79 20 74 68 65 72   is already ther
9490: 65 2e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  e.  [sqlite3_mut
94a0: 65 78 5f 74 72 79 28 29 5d 20 61 74 74 65 6d 70  ex_try()] attemp
94b0: 74 73 0a 20 20 74 6f 20 65 6e 74 65 72 20 61 6e  ts.  to enter an
94c0: 64 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  d returns [SQLIT
94d0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
94e0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   or [SQLITE_BUSY
94f0: 5d 20 69 66 20 61 6e 6f 74 68 65 72 0a 20 20 74  ] if another.  t
9500: 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79  hread is already
9510: 20 74 68 65 72 65 2e 20 20 5b 73 71 6c 69 74 65   there.  [sqlite
9520: 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d  3_mutex_leave()]
9530: 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 2e 0a   exits a mutex..
9540: 20 20 54 68 65 20 6d 75 74 65 78 20 69 73 20 68    The mutex is h
9550: 65 6c 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 75  eld until the nu
9560: 6d 62 65 72 20 6f 66 20 65 78 69 74 73 20 6d 61  mber of exits ma
9570: 74 63 68 65 73 20 74 68 65 20 6e 75 6d 62 65 72  tches the number
9580: 20 6f 66 0a 20 20 65 6e 74 72 61 6e 63 65 73 2e   of.  entrances.
9590: 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 6d 75    If [sqlite3_mu
95a0: 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 69 73 20  tex_leave()] is 
95b0: 63 61 6c 6c 65 64 20 6f 6e 20 61 20 6d 75 74 65  called on a mute
95c0: 78 20 74 68 61 74 20 0a 20 20 74 68 65 20 74 68  x that .  the th
95d0: 72 65 61 64 20 69 73 20 6e 6f 74 20 63 75 72 72  read is not curr
95e0: 65 6e 74 6c 79 20 68 6f 6c 64 69 6e 67 2c 20 74  ently holding, t
95f0: 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
9600: 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 20   is undefined.. 
9610: 20 49 66 20 61 6e 79 20 72 6f 75 74 69 6e 65 20   If any routine 
9620: 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 20  is called for a 
9630: 64 65 61 6c 6c 6f 63 61 74 65 64 20 6d 75 74 65  deallocated mute
9640: 78 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  x, then the beha
9650: 76 69 6f 72 0a 20 20 69 73 20 75 6e 64 65 66 69  vior.  is undefi
9660: 6e 65 64 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50  ned..}..PARAGRAP
9670: 48 20 7b 0a 20 20 54 68 65 20 53 51 4c 69 74 65  H {.  The SQLite
9680: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 70 72 6f   source code pro
9690: 76 69 64 65 73 20 6d 75 6c 74 69 70 6c 65 20 69  vides multiple i
96a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
96b0: 66 20 74 68 65 73 65 0a 20 20 41 50 49 73 2c 20  f these.  APIs, 
96c0: 73 75 69 74 61 62 6c 65 20 66 6f 72 20 76 61 72  suitable for var
96d0: 79 69 6e 67 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  ying environment
96e0: 73 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  s.  If SQLite is
96f0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 20   compiled with. 
9700: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45   the SQLITE_THRE
9710: 41 44 53 41 46 45 3d 30 20 66 6c 61 67 20 74 68  ADSAFE=0 flag th
9720: 65 6e 20 61 20 6e 6f 2d 6f 70 20 6d 75 74 65 78  en a no-op mutex
9730: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
9740: 74 68 61 74 20 0a 20 20 69 73 20 66 61 73 74 20  that .  is fast 
9750: 62 75 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c  but does no real
9760: 20 6d 75 74 75 61 6c 20 65 78 63 6c 75 73 69 6f   mutual exclusio
9770: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 2e 20 20  n is provided.  
9780: 54 68 61 74 20 0a 20 20 69 6d 70 6c 65 6d 65 6e  That .  implemen
9790: 74 61 74 69 6f 6e 20 69 73 20 73 75 69 74 61 62  tation is suitab
97a0: 6c 65 20 66 6f 72 20 75 73 65 20 69 6e 20 73 69  le for use in si
97b0: 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70  ngle-threaded ap
97c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 20 20 6f 72 20  plications.  or 
97d0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
97e0: 74 20 6f 6e 6c 79 20 75 73 65 20 53 51 4c 69 74  t only use SQLit
97f0: 65 20 69 6e 20 61 20 73 69 6e 67 6c 65 20 74 68  e in a single th
9800: 72 65 61 64 2e 20 20 4f 74 68 65 72 0a 20 20 72  read.  Other.  r
9810: 65 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  eal mutex implem
9820: 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 70 72  entations are pr
9830: 6f 76 69 64 65 64 20 62 61 73 65 64 20 6f 6e 20  ovided based on 
9840: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 20  the underlying. 
9850: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
9860: 6d 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50 48 20  m..}..PARAGRAPH 
9870: 7b 0a 20 20 45 6d 62 65 64 64 65 64 20 61 70 70  {.  Embedded app
9880: 6c 69 63 61 74 69 6f 6e 73 20 6d 61 79 20 77 69  lications may wi
9890: 73 68 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68  sh to provide th
98a0: 65 69 72 20 6f 77 6e 20 6d 75 74 65 78 20 69 6d  eir own mutex im
98b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 20 20  plementation..  
98c0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
98d0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 2d  piled with the -
98e0: 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50  DSQLITE_MUTEX_AP
98f0: 50 44 45 46 3d 31 20 63 6f 6d 70 69 6c 65 2d 74  PDEF=1 compile-t
9900: 69 6d 65 20 66 6c 61 67 0a 20 20 74 68 65 6e 20  ime flag.  then 
9910: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
9920: 70 72 6f 76 69 64 65 73 20 6e 6f 20 6d 75 74 65  provides no mute
9930: 78 20 73 75 62 73 79 73 74 65 6d 20 61 6e 64 20  x subsystem and 
9940: 61 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65  a mutex subsyste
9950: 6d 0a 20 20 74 68 61 74 20 6d 61 74 63 68 65 73  m.  that matches
9960: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 64   the interface d
9970: 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 20 6d  escribed above m
9980: 75 73 74 20 62 65 20 70 72 6f 76 69 64 65 64 20  ust be provided 
9990: 62 79 20 74 68 65 0a 20 20 61 70 70 6c 69 63 61  by the.  applica
99a0: 74 69 6f 6e 20 74 68 61 74 20 6c 69 6e 6b 73 20  tion that links 
99b0: 61 67 61 69 6e 73 74 20 53 51 4c 69 74 65 2e 0a  against SQLite..
99c0: 7d 0a 0a 48 45 41 44 49 4e 47 20 31 20 7b 4f 74  }..HEADING 1 {Ot
99d0: 68 65 72 20 49 6e 74 65 72 66 61 63 65 20 43 68  her Interface Ch
99e0: 61 6e 67 65 73 7d 0a 0a 50 41 52 41 47 52 41 50  anges}..PARAGRAP
99f0: 48 20 7b 0a 20 20 56 65 72 73 69 6f 6e 20 33 2e  H {.  Version 3.
9a00: 35 2e 30 20 6f 66 20 53 51 4c 69 74 65 20 63 68  5.0 of SQLite ch
9a10: 61 6e 67 65 73 20 74 68 65 20 62 65 68 61 76 69  anges the behavi
9a20: 6f 72 20 6f 66 20 61 20 66 65 77 20 41 50 49 73  or of a few APIs
9a30: 20 69 6e 20 77 61 79 73 0a 20 20 74 68 61 74 20   in ways.  that 
9a40: 61 72 65 20 74 65 63 68 6e 69 63 61 6c 6c 79 20  are technically 
9a50: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 2e 20 20 48  incompatible.  H
9a60: 6f 77 65 76 65 72 2c 20 74 68 65 73 65 20 41 50  owever, these AP
9a70: 49 73 20 61 72 65 20 73 65 6c 64 6f 6d 0a 20 20  Is are seldom.  
9a80: 75 73 65 64 20 61 6e 64 20 65 76 65 6e 20 77 68  used and even wh
9a90: 65 6e 20 74 68 65 79 20 61 72 65 20 75 73 65 64  en they are used
9aa0: 20 69 74 20 69 73 20 64 69 66 66 69 63 75 6c 74   it is difficult
9ab0: 20 74 6f 20 69 6d 61 67 69 6e 65 20 61 0a 20 20   to imagine a.  
9ac0: 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 74  scenario where t
9ad0: 68 65 20 63 68 61 6e 67 65 20 6d 69 67 68 74 20  he change might 
9ae0: 62 72 65 61 6b 20 73 6f 6d 65 74 68 69 6e 67 2e  break something.
9af0: 20 20 54 68 65 20 63 68 61 6e 67 65 73 0a 20 20    The changes.  
9b00: 61 63 74 75 61 6c 6c 79 20 6d 61 6b 65 73 20 74  actually makes t
9b10: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 20 6d  hese interface m
9b20: 75 63 68 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  uch more useful 
9b30: 61 6e 64 20 70 6f 77 65 72 66 75 6c 2e 0a 7d 0a  and powerful..}.
9b40: 0a 50 41 52 41 47 52 41 50 48 20 7b 0a 20 20 50  .PARAGRAPH {.  P
9b50: 72 69 6f 72 20 74 6f 20 76 65 72 73 69 6f 6e 20  rior to version 
9b60: 33 2e 35 2e 30 2c 20 74 68 65 20 5b 73 71 6c 69  3.5.0, the [sqli
9b70: 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
9b80: 64 5f 63 61 63 68 65 28 29 5d 20 41 50 49 0a 20  d_cache()] API. 
9b90: 20 77 6f 75 6c 64 20 65 6e 61 62 6c 65 20 61 6e   would enable an
9ba0: 64 20 64 69 73 61 62 6c 65 20 74 68 65 20 73 68  d disable the sh
9bb0: 61 72 65 64 20 63 61 63 68 65 20 66 65 61 74 75  ared cache featu
9bc0: 72 65 20 66 6f 72 20 61 6c 6c 20 63 6f 6e 6e 65  re for all conne
9bd0: 63 74 69 6f 6e 73 0a 20 20 77 69 74 68 69 6e 20  ctions.  within 
9be0: 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
9bf0: 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  - the same threa
9c00: 64 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  d from which the
9c10: 20 0a 20 20 73 71 6c 69 74 65 33 5f 65 6e 61 62   .  sqlite3_enab
9c20: 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
9c30: 29 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  ) routine was ca
9c40: 6c 6c 65 64 2e 20 20 44 61 74 61 62 61 73 65 20  lled.  Database 
9c50: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 20 20 74 68  connections.  th
9c60: 61 74 20 75 73 65 64 20 74 68 65 20 73 68 61 72  at used the shar
9c70: 65 64 20 63 61 63 68 65 20 77 65 72 65 20 72 65  ed cache were re
9c80: 73 74 72 69 63 74 65 64 20 74 6f 20 72 75 6e 6e  stricted to runn
9c90: 69 6e 67 20 69 6e 20 74 68 65 20 73 61 6d 65 0a  ing in the same.
9ca0: 20 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63    thread in whic
9cb0: 68 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  h they were open
9cc0: 65 64 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ed.  Beginning w
9cd0: 69 74 68 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ith version 3.5.
9ce0: 30 2c 0a 20 20 74 68 65 20 73 71 6c 69 74 65 33  0,.  the sqlite3
9cf0: 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
9d00: 61 63 68 65 28 29 20 61 70 70 6c 69 65 73 20 74  ache() applies t
9d10: 6f 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  o all database c
9d20: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 20 20 69 6e 20  onnections.  in 
9d30: 61 6c 6c 20 74 68 72 65 61 64 73 20 77 69 74 68  all threads with
9d40: 69 6e 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  in the process. 
9d50: 20 4e 6f 77 20 64 61 74 61 62 61 73 65 20 63 6f   Now database co
9d60: 6e 6e 65 63 74 69 6f 6e 73 20 72 75 6e 6e 69 6e  nnections runnin
9d70: 67 0a 20 20 69 6e 20 73 65 70 61 72 61 74 65 20  g.  in separate 
9d80: 74 68 72 65 61 64 73 20 63 61 6e 20 73 68 61 72  threads can shar
9d90: 65 20 61 20 63 61 63 68 65 2e 20 20 41 6e 64 20  e a cache.  And 
9da0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9db0: 69 6f 6e 73 20 74 68 61 74 0a 20 20 75 73 65 20  ions that.  use 
9dc0: 73 68 61 72 65 64 20 63 61 63 68 65 20 63 61 6e  shared cache can
9dd0: 20 6d 69 67 72 61 74 65 20 66 72 6f 6d 20 6f 6e   migrate from on
9de0: 65 20 74 68 72 65 61 64 20 74 6f 20 61 6e 6f 74  e thread to anot
9df0: 68 65 72 2e 0a 7d 0a 0a 50 41 52 41 47 52 41 50  her..}..PARAGRAP
9e00: 48 20 7b 0a 20 20 50 72 69 6f 72 20 74 6f 20 76  H {.  Prior to v
9e10: 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65  ersion 3.5.0 the
9e20: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
9e30: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 20 73 65 74  eap_limit()] set
9e40: 20 61 6e 20 75 70 70 65 72 0a 20 20 62 6f 75 6e   an upper.  boun
9e50: 64 20 6f 6e 20 68 65 61 70 20 6d 65 6d 6f 72 79  d on heap memory
9e60: 20 75 73 61 67 65 20 66 6f 72 20 61 6c 6c 20 64   usage for all d
9e70: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9e80: 6f 6e 73 20 77 69 74 68 69 6e 20 61 0a 20 20 73  ons within a.  s
9e90: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 45  ingle thread.  E
9ea0: 61 63 68 20 74 68 72 65 61 64 20 63 6f 75 6c 64  ach thread could
9eb0: 20 68 61 76 65 20 69 74 73 20 6f 77 6e 20 68 65   have its own he
9ec0: 61 70 20 6c 69 6d 69 74 2e 20 20 42 65 67 69 6e  ap limit.  Begin
9ed0: 6e 69 6e 67 0a 20 20 69 6e 20 76 65 72 73 69 6f  ning.  in versio
9ee0: 6e 20 33 2e 35 2e 30 2c 20 74 68 65 72 65 20 69  n 3.5.0, there i
9ef0: 73 20 61 20 73 69 6e 67 6c 65 20 68 65 61 70 20  s a single heap 
9f00: 6c 69 6d 69 74 20 66 6f 72 20 74 68 65 20 65 6e  limit for the en
9f10: 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 20 20  tire process..  
9f20: 54 68 69 73 20 73 65 65 6d 73 20 6d 6f 72 65 20  This seems more 
9f30: 72 65 73 74 72 69 63 74 69 76 65 20 28 6f 6e 65  restrictive (one
9f40: 20 6c 69 6d 69 74 20 61 73 20 6f 70 70 6f 73 65   limit as oppose
9f50: 64 20 74 6f 20 6d 61 6e 79 29 20 62 75 74 20 69  d to many) but i
9f60: 6e 0a 20 20 70 72 61 63 74 69 63 65 20 69 74 20  n.  practice it 
9f70: 69 73 20 77 68 61 74 20 6d 6f 73 74 20 75 73 65  is what most use
9f80: 72 73 20 77 61 6e 74 2e 0a 7d 0a 0a 50 41 52 41  rs want..}..PARA
9f90: 47 52 41 50 48 20 7b 0a 20 20 50 72 69 6f 72 20  GRAPH {.  Prior 
9fa0: 74 6f 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  to version 3.5.0
9fb0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
9fc0: 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
9fd0: 66 75 6e 63 74 69 6f 6e 20 77 6f 75 6c 64 0a 20  function would. 
9fe0: 20 74 72 79 20 74 6f 20 72 65 63 6c 61 69 6d 20   try to reclaim 
9ff0: 6d 65 6d 6f 72 79 20 66 72 6f 6d 20 61 6c 6c 20  memory from all 
a000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a010: 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
a020: 20 74 68 72 65 61 64 0a 20 20 61 73 20 74 68 65   thread.  as the
a030: 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
a040: 5f 6d 65 6d 6f 72 79 28 29 20 63 61 6c 6c 2e 20  _memory() call. 
a050: 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
a060: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 0a 20  version 3.5.0,. 
a070: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c   the sqlite3_rel
a080: 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 66 75  ease_memory() fu
a090: 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 74 74 65  nction will atte
a0a0: 6d 70 74 20 74 6f 20 72 65 63 6c 61 69 6d 20 6d  mpt to reclaim m
a0b0: 65 6d 6f 72 79 0a 20 20 66 72 6f 6d 20 61 6c 6c  emory.  from all
a0c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a0d0: 74 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72  tions in all thr
a0e0: 65 61 64 73 2e 0a 7d 0a 0a 48 45 41 44 49 4e 47  eads..}..HEADING
a0f0: 20 31 20 7b 53 75 6d 6d 61 72 79 7d 0a 0a 50 41   1 {Summary}..PA
a100: 52 41 47 52 41 50 48 20 7b 0a 20 20 54 68 65 20  RAGRAPH {.  The 
a110: 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 20  transition from 
a120: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
a130: 2e 34 2e 32 20 74 6f 20 33 2e 35 2e 30 20 69 73  .4.2 to 3.5.0 is
a140: 20 61 20 6d 61 6a 6f 72 20 63 68 61 6e 67 65 2e   a major change.
a150: 0a 20 20 45 76 65 72 79 20 73 6f 75 72 63 65 20  .  Every source 
a160: 63 6f 64 65 20 66 69 6c 65 20 69 6e 20 74 68 65  code file in the
a170: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 68 61 64   SQLite core had
a180: 20 74 6f 20 62 65 20 6d 6f 64 69 66 69 65 64 2c   to be modified,
a190: 20 73 6f 6d 65 0a 20 20 65 78 74 65 6e 73 69 76   some.  extensiv
a1a0: 65 6c 79 2e 20 20 41 6e 64 20 74 68 65 20 63 68  ely.  And the ch
a1b0: 61 6e 67 65 20 69 6e 74 72 6f 64 75 63 65 64 20  ange introduced 
a1c0: 73 6f 6d 65 20 6d 69 6e 6f 72 20 69 6e 63 6f 6d  some minor incom
a1d0: 70 61 74 69 62 69 6c 69 74 69 65 73 0a 20 20 69  patibilities.  i
a1e0: 6e 20 74 68 65 20 43 20 69 6e 74 65 72 66 61 63  n the C interfac
a1f0: 65 2e 20 20 42 75 74 20 77 65 20 66 65 65 6c 20  e.  But we feel 
a200: 74 68 61 74 20 74 68 65 20 62 65 6e 65 66 69 74  that the benefit
a210: 73 20 6f 66 20 74 68 65 20 74 72 61 6e 73 69 74  s of the transit
a220: 69 6f 6e 0a 20 20 66 72 6f 6d 20 33 2e 34 2e 32  ion.  from 3.4.2
a230: 20 74 6f 20 33 2e 35 2e 30 20 66 61 72 20 6f 75   to 3.5.0 far ou
a240: 74 77 65 69 67 68 20 74 68 65 20 70 61 69 6e 20  tweigh the pain 
a250: 6f 66 20 70 6f 72 74 69 6e 67 2e 20 20 54 68 65  of porting.  The
a260: 20 6e 65 77 0a 20 20 56 46 53 20 6c 61 79 65 72   new.  VFS layer
a270: 20 69 73 20 6e 6f 77 20 77 65 6c 6c 2d 64 65 66   is now well-def
a280: 69 6e 65 64 20 61 6e 64 20 73 74 61 62 6c 65 20  ined and stable 
a290: 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6d 70 6c  and should simpl
a2a0: 69 66 79 20 66 75 74 75 72 65 0a 20 20 63 75 73  ify future.  cus
a2b0: 74 6f 6d 69 7a 61 74 69 6f 6e 73 2e 20 20 54 68  tomizations.  Th
a2c0: 65 20 56 46 53 20 6c 61 79 65 72 2c 20 61 6e 64  e VFS layer, and
a2d0: 20 74 68 65 20 73 65 70 61 72 61 62 6c 65 20 6d   the separable m
a2e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 0a  emory allocator.
a2f0: 20 20 61 6e 64 20 6d 75 74 65 78 20 73 75 62 73    and mutex subs
a300: 79 73 74 65 6d 73 20 61 6c 6c 6f 77 20 61 20 73  ystems allow a s
a310: 74 61 6e 64 61 72 64 20 53 51 4c 69 74 65 20 73  tandard SQLite s
a320: 6f 75 72 63 65 20 63 6f 64 65 20 61 6d 61 6c 67  ource code amalg
a330: 61 6d 61 74 69 6f 6e 0a 20 20 74 6f 20 62 65 20  amation.  to be 
a340: 75 73 65 64 20 69 6e 20 61 6e 20 65 6d 62 65 64  used in an embed
a350: 64 65 64 20 70 72 6f 6a 65 63 74 20 77 69 74 68  ded project with
a360: 6f 75 74 20 63 68 61 6e 67 65 2c 20 67 72 65 61  out change, grea
a370: 74 6c 79 20 73 69 6d 70 6c 69 66 79 69 6e 67 0a  tly simplifying.
a380: 20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20    configuration 
a390: 6d 61 6e 61 67 65 6d 65 6e 74 2e 20 20 41 6e 64  management.  And
a3a0: 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
a3b0: 79 73 74 65 6d 20 69 73 20 6d 75 63 68 20 6d 6f  ystem is much mo
a3c0: 72 65 0a 20 20 74 6f 6c 65 72 61 6e 74 20 6f 66  re.  tolerant of
a3d0: 20 68 69 67 68 6c 79 20 74 68 72 65 61 64 65 64   highly threaded
a3e0: 20 64 65 73 69 67 6e 73 2e 0a 7d 0a 3c 2f 74 63   designs..}.</tc
a3f0: 6c 3e 0a                                         l>.