Documentation Source Text

Hex Artifact Content
Login

Artifact 0a3fb9102133c01a446e96da24fa27f0c9fb4decf4e583a86a17459186609933:


0000: 3c 74 69 74 6c 65 3e 54 68 65 20 53 51 4c 69 74  <title>The SQLit
0010: 65 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 6f  e OS Interface o
0020: 72 20 22 56 46 53 22 3c 2f 74 69 74 6c 65 3e 0a  r "VFS"</title>.
0030: 3c 74 63 6c 3e 68 64 5f 6b 65 79 77 6f 72 64 73  <tcl>hd_keywords
0040: 20 56 46 53 20 56 46 53 65 73 20 7b 4f 53 20 62   VFS VFSes {OS b
0050: 61 63 6b 65 6e 64 7d 3c 2f 74 63 6c 3e 0a 0a 3c  ackend}</tcl>..<
0060: 74 61 62 6c 65 5f 6f 66 5f 63 6f 6e 74 65 6e 74  table_of_content
0070: 73 3e 0a 0a 3c 68 31 3e 49 6e 74 72 6f 64 75 63  s>..<h1>Introduc
0080: 74 69 6f 6e 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a 54  tion</h1>..<p>.T
0090: 68 69 73 20 61 72 74 69 63 6c 65 20 64 65 73 63  his article desc
00a0: 72 69 62 65 73 20 74 68 65 20 53 51 4c 69 74 65  ribes the SQLite
00b0: 20 4f 53 20 70 6f 72 74 61 62 69 6c 69 74 79 20   OS portability 
00c0: 6c 61 79 65 72 20 6f 72 20 22 56 46 53 22 20 2d  layer or "VFS" -
00d0: 20 74 68 65 0a 6d 6f 64 75 6c 65 20 61 74 20 74   the.module at t
00e0: 68 65 20 62 6f 74 74 6f 6d 20 6f 66 20 74 68 65  he bottom of the
00f0: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
0100: 74 61 74 69 6f 6e 20 73 74 61 63 6b 0a 74 68 61  tation stack.tha
0110: 74 20 70 72 6f 76 69 64 65 73 20 70 6f 72 74 61  t provides porta
0120: 62 69 6c 69 74 79 20 61 63 72 6f 73 73 20 6f 70  bility across op
0130: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 2e  erating systems.
0140: 0a 3c 2f 70 3e 0a 0a 3c 68 31 3e 54 68 65 20 56  .</p>..<h1>The V
0150: 46 53 20 49 6e 20 52 65 6c 61 74 69 6f 6e 20 54  FS In Relation T
0160: 6f 20 54 68 65 20 52 65 73 74 20 4f 66 20 53 51  o The Rest Of SQ
0170: 4c 69 74 65 3c 2f 68 31 3e 0a 0a 3c 64 69 76 3e  Lite</h1>..<div>
0180: 0a 3c 69 6d 67 20 73 72 63 3d 22 69 6d 61 67 65  .<img src="image
0190: 73 2f 76 66 73 31 2e 67 69 66 22 20 61 6c 69 67  s/vfs1.gif" alig
01a0: 6e 3d 22 72 69 67 68 74 22 20 68 73 70 61 63 65  n="right" hspace
01b0: 3d 22 31 30 22 3e 0a 3c 2f 64 69 76 3e 0a 0a 3c  ="10">.</div>..<
01c0: 70 3e 0a 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  p>.The internal 
01d0: 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 20 6f 66 20  organization of 
01e0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
01f0: 72 79 20 63 61 6e 20 62 65 20 76 69 65 77 65 64  ry can be viewed
0200: 20 61 73 20 74 68 65 0a 73 74 61 63 6b 20 6f 66   as the.stack of
0210: 20 6d 6f 64 75 6c 65 73 20 73 68 6f 77 6e 20 74   modules shown t
0220: 6f 20 74 68 65 20 72 69 67 68 74 2e 0a 54 68 65  o the right..The
0230: 20 54 6f 6b 65 6e 69 7a 65 72 2c 20 50 61 72 73   Tokenizer, Pars
0240: 65 72 2c 20 61 6e 64 20 43 6f 64 65 20 47 65 6e  er, and Code Gen
0250: 65 72 61 74 6f 72 20 63 6f 6d 70 6f 6e 65 6e 74  erator component
0260: 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 70 72  s are used to.pr
0270: 6f 63 65 73 73 20 53 51 4c 20 73 74 61 74 65 6d  ocess SQL statem
0280: 65 6e 74 73 20 61 6e 64 20 63 6f 6e 76 65 72 74  ents and convert
0290: 20 74 68 65 6d 20 69 6e 74 6f 20 65 78 65 63 75   them into execu
02a0: 74 61 62 6c 65 20 70 72 6f 67 72 61 6d 73 20 0a  table programs .
02b0: 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
02c0: 68 69 6e 65 20 6c 61 6e 67 75 61 67 65 20 6f 72  hine language or
02d0: 20 62 79 74 65 20 63 6f 64 65 2e 0a 52 6f 75 67   byte code..Roug
02e0: 68 6c 79 20 73 70 65 61 6b 69 6e 67 2c 20 74 68  hly speaking, th
02f0: 65 73 65 20 74 6f 70 20 74 68 72 65 65 20 6c 61  ese top three la
0300: 79 65 72 73 20 69 6d 70 6c 65 6d 65 6e 74 0a 5b  yers implement.[
0310: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
0320: 76 32 28 29 5d 2e 20 20 54 68 65 20 62 79 74 65  v2()].  The byte
0330: 20 63 6f 64 65 20 67 65 6e 65 72 61 74 65 64 20   code generated 
0340: 62 79 20 74 68 65 20 74 6f 70 20 74 68 72 65 65  by the top three
0350: 0a 6c 61 79 65 72 73 20 69 73 20 61 20 5b 70 72  .layers is a [pr
0360: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
0370: 5d 2e 0a 54 68 65 20 56 69 72 74 75 61 6c 20 4d  ]..The Virtual M
0380: 61 63 68 69 6e 65 20 6d 6f 64 75 6c 65 20 69 73  achine module is
0390: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
03a0: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 53 51 4c   running the SQL
03b0: 20 73 74 61 74 65 6d 65 6e 74 20 0a 62 79 74 65   statement .byte
03c0: 20 63 6f 64 65 2e 20 54 68 65 20 42 2d 54 72 65   code. The B-Tre
03d0: 65 20 6d 6f 64 75 6c 65 20 6f 72 67 61 6e 69 7a  e module organiz
03e0: 65 73 20 61 20 64 61 74 61 62 61 73 65 20 66 69  es a database fi
03f0: 6c 65 20 69 6e 74 6f 20 6d 75 6c 74 69 70 6c 65  le into multiple
0400: 20 0a 6b 65 79 2f 76 61 6c 75 65 20 73 74 6f 72   .key/value stor
0410: 65 73 20 77 69 74 68 20 6f 72 64 65 72 65 64 20  es with ordered 
0420: 6b 65 79 73 20 61 6e 64 20 6c 6f 67 61 72 69 74  keys and logarit
0430: 68 6d 69 63 20 70 65 72 66 6f 72 6d 61 6e 63 65  hmic performance
0440: 2e 20 0a 54 68 65 20 50 61 67 65 72 20 6d 6f 64  . .The Pager mod
0450: 75 6c 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ule is responsib
0460: 6c 65 20 66 6f 72 20 6c 6f 61 64 69 6e 67 20 70  le for loading p
0470: 61 67 65 73 20 6f 66 20 74 68 65 20 64 61 74 61  ages of the data
0480: 62 61 73 65 0a 66 69 6c 65 20 69 6e 74 6f 20 6d  base.file into m
0490: 65 6d 6f 72 79 2c 20 66 6f 72 20 69 6d 70 6c 65  emory, for imple
04a0: 6d 65 6e 74 69 6e 67 20 61 6e 64 20 63 6f 6e 74  menting and cont
04b0: 72 6f 6c 6c 69 6e 67 20 74 72 61 6e 73 61 63 74  rolling transact
04c0: 69 6f 6e 73 2c 20 61 6e 64 20 0a 66 6f 72 20 63  ions, and .for c
04d0: 72 65 61 74 69 6e 67 20 61 6e 64 20 6d 61 69 6e  reating and main
04e0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6a 6f 75 72  taining the jour
04f0: 6e 61 6c 20 66 69 6c 65 73 20 74 68 61 74 20 70  nal files that p
0500: 72 65 76 65 6e 74 20 64 61 74 61 62 61 73 65 20  revent database 
0510: 0a 63 6f 72 72 75 70 74 69 6f 6e 20 66 6f 6c 6c  .corruption foll
0520: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
0530: 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 2e 20   power failure. 
0540: 0a 54 68 65 20 4f 53 20 49 6e 74 65 72 66 61 63  .The OS Interfac
0550: 65 20 69 73 20 61 20 74 68 69 6e 20 61 62 73 74  e is a thin abst
0560: 72 61 63 74 69 6f 6e 20 74 68 61 74 20 70 72 6f  raction that pro
0570: 76 69 64 65 73 20 61 20 63 6f 6d 6d 6f 6e 20 73  vides a common s
0580: 65 74 20 6f 66 20 0a 72 6f 75 74 69 6e 65 73 20  et of .routines 
0590: 66 6f 72 20 61 64 61 70 74 69 6e 67 20 53 51 4c  for adapting SQL
05a0: 69 74 65 20 74 6f 20 72 75 6e 20 6f 6e 20 64 69  ite to run on di
05b0: 66 66 65 72 65 6e 74 20 6f 70 65 72 61 74 69 6e  fferent operatin
05c0: 67 20 73 79 73 74 65 6d 73 2e 0a 52 6f 75 67 68  g systems..Rough
05d0: 6c 79 20 73 70 65 61 6b 69 6e 67 2c 20 74 68 65  ly speaking, the
05e0: 20 62 6f 74 74 6f 6d 20 66 6f 75 72 20 6c 61 79   bottom four lay
05f0: 65 72 73 20 69 6d 70 6c 65 6d 65 6e 74 0a 5b 73  ers implement.[s
0600: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
0610: 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 69 73 20 61  </p>..<p>.This a
0620: 72 74 69 63 6c 65 20 69 73 20 61 62 6f 75 74 20  rticle is about 
0630: 74 68 65 20 62 6f 74 74 6f 6d 20 6c 61 79 65 72  the bottom layer
0640: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 4f  ..</p>..<p>The O
0650: 53 20 49 6e 74 65 72 66 61 63 65 20 2d 20 61 6c  S Interface - al
0660: 73 6f 20 63 61 6c 6c 65 64 20 74 68 65 20 22 56  so called the "V
0670: 46 53 22 20 2d 20 69 73 20 77 68 61 74 20 6d 61  FS" - is what ma
0680: 6b 65 73 20 53 51 4c 69 74 65 20 0a 70 6f 72 74  kes SQLite .port
0690: 61 62 6c 65 20 61 63 72 6f 73 73 20 6f 70 65 72  able across oper
06a0: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 2e 20 20  ating systems.  
06b0: 57 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  Whenever any of 
06c0: 74 68 65 20 6f 74 68 65 72 20 6d 6f 64 75 6c 65  the other module
06d0: 73 0a 69 6e 20 53 51 4c 69 74 65 20 6e 65 65 64  s.in SQLite need
06e0: 73 20 74 6f 20 63 6f 6d 6d 75 6e 69 63 61 74 65  s to communicate
06f0: 20 77 69 74 68 20 74 68 65 20 6f 70 65 72 61 74   with the operat
0700: 69 6e 67 0a 73 79 73 74 65 6d 2c 20 74 68 65 79  ing.system, they
0710: 20 69 6e 76 6f 6b 65 20 6d 65 74 68 6f 64 73 20   invoke methods 
0720: 69 6e 20 74 68 65 20 56 46 53 2e 20 20 54 68 65  in the VFS.  The
0730: 20 56 46 53 20 74 68 65 6e 20 69 6e 76 6f 6b 65   VFS then invoke
0740: 73 20 74 68 65 0a 6f 70 65 72 61 74 69 6e 67 2d  s the.operating-
0750: 73 70 65 63 69 66 69 63 20 63 6f 64 65 20 6e 65  specific code ne
0760: 65 64 65 64 20 74 6f 20 73 61 74 69 73 66 79 20  eded to satisfy 
0770: 74 68 65 20 72 65 71 75 65 73 74 2e 0a 48 65 6e  the request..Hen
0780: 63 65 2c 20 70 6f 72 74 69 6e 67 20 53 51 4c 69  ce, porting SQLi
0790: 74 65 20 74 6f 20 61 20 6e 65 77 0a 6f 70 65 72  te to a new.oper
07a0: 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
07b0: 73 69 6d 70 6c 79 20 61 20 6d 61 74 74 65 72 20  simply a matter 
07c0: 6f 66 20 77 72 69 74 69 6e 67 20 61 20 6e 65 77  of writing a new
07d0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
07e0: 79 65 72 0a 6f 72 20 22 56 46 53 22 2e 3c 2f 70  yer.or "VFS".</p
07f0: 3e 0a 0a 3c 68 31 3e 4d 75 6c 74 69 70 6c 65 20  >..<h1>Multiple 
0800: 56 46 53 65 73 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a  VFSes</h1>..<p>.
0810: 54 68 65 20 73 74 61 6e 64 61 72 64 20 53 51 4c  The standard SQL
0820: 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 20  ite source tree 
0830: 63 6f 6e 74 61 69 6e 73 20 62 75 69 6c 74 2d 69  contains built-i
0840: 6e 20 56 46 53 65 73 20 66 6f 72 20 75 6e 69 78  n VFSes for unix
0850: 0a 61 6e 64 20 77 69 6e 64 6f 77 73 2e 20 20 41  .and windows.  A
0860: 6c 74 65 72 6e 61 74 69 76 65 20 56 46 53 65 73  lternative VFSes
0870: 20 63 61 6e 20 62 65 0a 61 64 64 65 64 20 61 74   can be.added at
0880: 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 72 20 72   start-time or r
0890: 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 74 68  un-time using th
08a0: 65 0a 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e.[sqlite3_vfs_r
08b0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
08c0: 66 61 63 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a  face..</p>..<p>.
08d0: 4d 75 6c 74 69 70 6c 65 20 56 46 53 65 73 20 63  Multiple VFSes c
08e0: 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
08f0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
0900: 65 2e 0a 45 61 63 68 20 56 46 53 20 68 61 73 20  e..Each VFS has 
0910: 61 20 75 6e 69 71 75 65 20 6e 61 6d 65 73 2e 0a  a unique names..
0920: 53 65 70 61 72 61 74 65 20 5b 64 61 74 61 62 61  Separate [databa
0930: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
0940: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
0950: 70 72 6f 63 65 73 73 20 63 61 6e 20 62 65 20 75  process can be u
0960: 73 69 6e 67 0a 64 69 66 66 65 72 65 6e 74 20 56  sing.different V
0970: 46 53 65 73 20 61 74 20 74 68 65 20 73 61 6d 65  FSes at the same
0980: 20 74 69 6d 65 2e 20 20 20 46 6f 72 20 74 68 61   time.   For tha
0990: 74 20 6d 61 74 74 65 72 2c 20 69 66 20 61 20 73  t matter, if a s
09a0: 69 6e 67 6c 65 0a 64 61 74 61 62 61 73 65 20 63  ingle.database c
09b0: 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 6d 75  onnection has mu
09c0: 6c 74 69 70 6c 65 20 64 61 74 61 62 61 73 65 20  ltiple database 
09d0: 66 69 6c 65 73 20 6f 70 65 6e 20 75 73 69 6e 67  files open using
09e0: 0a 74 68 65 20 5b 41 54 54 41 43 48 5d 20 63 6f  .the [ATTACH] co
09f0: 6d 6d 61 6e 64 2c 20 74 68 65 6e 20 65 61 63 68  mmand, then each
0a00: 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
0a10: 73 65 20 6d 69 67 68 74 20 62 65 20 75 73 69 6e  se might be usin
0a20: 67 20 61 0a 64 69 66 66 65 72 65 6e 74 20 56 46  g a.different VF
0a30: 53 2e 0a 3c 2f 70 3e 0a 0a 3c 68 32 3e 53 74 61  S..</p>..<h2>Sta
0a40: 6e 64 61 72 64 20 55 6e 69 78 20 56 46 53 65 73  ndard Unix VFSes
0a50: 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 55 6e 69 78 20  </h2>..<p>.Unix 
0a60: 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68  builds come with
0a70: 20 6d 75 6c 74 69 70 6c 65 20 62 75 69 6c 74 2d   multiple built-
0a80: 69 6e 20 56 46 53 65 73 2e 20 20 54 68 65 20 64  in VFSes.  The d
0a90: 65 66 61 75 6c 74 20 56 46 53 0a 66 6f 72 20 75  efault VFS.for u
0aa0: 6e 69 78 20 69 73 20 63 61 6c 6c 65 64 20 22 75  nix is called "u
0ab0: 6e 69 78 22 20 61 6e 64 20 69 73 20 75 73 65 64  nix" and is used
0ac0: 20 69 6e 20 6d 6f 73 74 20 61 70 70 6c 69 63 61   in most applica
0ad0: 74 69 6f 6e 73 2e 0a 4f 74 68 65 72 20 56 46 53  tions..Other VFS
0ae0: 65 73 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  es that might be
0af0: 20 66 6f 75 6e 64 20 69 6e 20 75 6e 69 78 20 28   found in unix (
0b00: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 63 6f 6d  depending on com
0b10: 70 69 6c 65 2d 74 69 6d 65 0a 6f 70 74 69 6f 6e  pile-time.option
0b20: 73 29 20 69 6e 63 6c 75 64 65 3a 0a 3c 2f 70 3e  s) include:.</p>
0b30: 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 3c 62  ..<ol>.<li><p><b
0b40: 3e 75 6e 69 78 2d 64 6f 74 66 69 6c 65 3c 2f 62  >unix-dotfile</b
0b50: 3e 20 2d 20 75 73 65 73 20 64 6f 74 2d 66 69 6c  > - uses dot-fil
0b60: 65 20 6c 6f 63 6b 69 6e 67 20 72 61 74 68 65 72  e locking rather
0b70: 20 74 68 61 6e 0a 20 20 20 20 20 20 20 20 20 20   than.          
0b80: 50 4f 53 49 58 20 61 64 76 69 73 6f 72 79 20 6c  POSIX advisory l
0b90: 6f 63 6b 73 2e 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e  ocks..<li><p><b>
0ba0: 75 6e 69 78 2d 65 78 63 6c 3c 2f 62 3e 20 2d 20  unix-excl</b> - 
0bb0: 6f 62 74 61 69 6e 73 20 61 6e 64 20 68 6f 6c 64  obtains and hold
0bc0: 73 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  s an exclusive l
0bd0: 6f 63 6b 20 6f 6e 0a 20 20 20 20 20 20 20 20 20  ock on.         
0be0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2c   database files,
0bf0: 20 70 72 65 76 65 6e 74 69 6e 67 20 6f 74 68 65   preventing othe
0c00: 72 20 70 72 6f 63 65 73 73 65 73 20 66 72 6f 6d  r processes from
0c10: 20 61 63 63 65 73 73 69 6e 67 20 74 68 65 0a 20   accessing the. 
0c20: 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
0c30: 65 2e 20 20 41 6c 73 6f 20 6b 65 65 70 73 20 74  e.  Also keeps t
0c40: 68 65 20 5b 77 61 6c 2d 69 6e 64 65 78 5d 20 69  he [wal-index] i
0c50: 6e 20 68 65 61 70 20 72 61 74 68 65 72 20 74 68  n heap rather th
0c60: 61 6e 20 69 6e 0a 20 20 20 20 20 20 20 20 20 20  an in.          
0c70: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 2e 0a 3c  shared memory..<
0c80: 6c 69 3e 3c 70 3e 3c 62 3e 75 6e 69 78 2d 6e 6f  li><p><b>unix-no
0c90: 6e 65 3c 2f 62 3e 20 2d 20 61 6c 6c 20 66 69 6c  ne</b> - all fil
0ca0: 65 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  e locking operat
0cb0: 69 6f 6e 73 20 61 72 65 20 6e 6f 2d 6f 70 73 2e  ions are no-ops.
0cc0: 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e 75 6e 69 78 2d  .<li><p><b>unix-
0cd0: 6e 61 6d 65 64 73 65 6d 3c 2f 62 3e 20 2d 20 75  namedsem</b> - u
0ce0: 73 65 73 20 6e 61 6d 65 64 20 73 65 6d 61 70 68  ses named semaph
0cf0: 6f 72 65 73 20 66 6f 72 20 66 69 6c 65 20 6c 6f  ores for file lo
0d00: 63 6b 69 6e 67 2e 0a 20 20 20 20 20 20 20 56 58  cking..       VX
0d10: 57 6f 72 6b 73 20 6f 6e 6c 79 2e 0a 3c 2f 6f 6c  Works only..</ol
0d20: 3e 0a 0a 3c 70 3e 0a 54 68 65 20 76 61 72 69 6f  >..<p>.The vario
0d30: 75 73 20 75 6e 69 78 20 56 46 53 65 73 20 64 69  us unix VFSes di
0d40: 66 66 65 72 20 6f 6e 6c 79 20 69 6e 20 74 68 65  ffer only in the
0d50: 20 77 61 79 20 74 68 65 79 20 68 61 6e 64 6c 65   way they handle
0d60: 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 2d 0a   file locking -.
0d70: 74 68 65 79 20 73 68 61 72 65 20 6d 6f 73 74 20  they share most 
0d80: 6f 66 20 74 68 65 69 72 20 69 6d 70 6c 65 6d 65  of their impleme
0d90: 6e 74 61 74 69 6f 6e 20 69 6e 20 63 6f 6d 6d 6f  ntation in commo
0da0: 6e 20 77 69 74 68 20 6f 6e 65 20 61 6e 6f 74 68  n with one anoth
0db0: 65 72 20 61 6e 64 0a 61 72 65 20 61 6c 6c 20 6c  er and.are all l
0dc0: 6f 63 61 74 65 64 20 69 6e 20 74 68 65 20 73 61  ocated in the sa
0dd0: 6d 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  me SQLite source
0de0: 20 66 69 6c 65 3a 20 20 0a 5b 68 74 74 70 3a 2f   file:  .[http:/
0df0: 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f  /www.sqlite.org/
0e00: 73 72 63 2f 64 6f 63 2f 74 72 75 6e 6b 2f 73 72  src/doc/trunk/sr
0e10: 63 2f 6f 73 5f 75 6e 69 78 2e 63 20 7c 20 6f 73  c/os_unix.c | os
0e20: 5f 75 6e 69 78 2e 63 5d 2e 0a 4e 6f 74 65 20 74  _unix.c]..Note t
0e30: 68 61 74 20 65 78 63 65 70 74 20 66 6f 72 20 22  hat except for "
0e40: 75 6e 69 78 22 20 61 6e 64 20 22 75 6e 69 78 2d  unix" and "unix-
0e50: 65 78 63 6c 22 2c 20 74 68 65 20 76 61 72 69 6f  excl", the vario
0e60: 75 73 20 75 6e 69 78 20 56 46 53 65 73 20 61 6c  us unix VFSes al
0e70: 6c 0a 75 73 65 20 69 6e 63 6f 6d 70 61 74 69 62  l.use incompatib
0e80: 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6d 70 6c 65  le locking imple
0e90: 6d 65 6e 74 61 74 69 6f 6e 73 2e 20 20 49 66 20  mentations.  If 
0ea0: 74 77 6f 20 70 72 6f 63 65 73 73 65 73 20 61 72  two processes ar
0eb0: 65 20 61 63 63 65 73 73 69 6e 67 0a 74 68 65 20  e accessing.the 
0ec0: 73 61 6d 65 20 53 51 4c 69 74 65 20 64 61 74 61  same SQLite data
0ed0: 62 61 73 65 20 75 73 69 6e 67 20 64 69 66 66 65  base using diffe
0ee0: 72 65 6e 74 20 75 6e 69 78 20 56 46 53 65 73 2c  rent unix VFSes,
0ef0: 20 74 68 65 79 20 6d 61 79 0a 6e 6f 74 20 73 65   they may.not se
0f00: 65 20 65 61 63 68 20 6f 74 68 65 72 73 20 6c 6f  e each others lo
0f10: 63 6b 73 20 61 6e 64 20 6d 61 79 20 65 6e 64 20  cks and may end 
0f20: 75 70 20 69 6e 74 65 72 66 65 72 69 6e 67 20 77  up interfering w
0f30: 69 74 68 20 6f 6e 65 20 61 6e 6f 74 68 65 72 2c  ith one another,
0f40: 0a 72 65 73 75 6c 74 69 6e 67 20 69 6e 20 64 61  .resulting in da
0f50: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
0f60: 6e 2e 20 20 54 68 65 20 22 75 6e 69 78 2d 6e 6f  n.  The "unix-no
0f70: 6e 65 22 20 56 46 53 20 69 6e 20 70 61 72 74 69  ne" VFS in parti
0f80: 63 75 6c 61 72 0a 64 6f 65 73 20 6e 6f 20 6c 6f  cular.does no lo
0f90: 63 6b 69 6e 67 20 61 74 20 61 6c 6c 20 61 6e 64  cking at all and
0fa0: 20 77 69 6c 6c 20 65 61 73 69 6c 79 20 72 65 73   will easily res
0fb0: 75 6c 74 20 69 6e 20 64 61 74 61 62 61 73 65 20  ult in database 
0fc0: 63 6f 72 72 75 70 74 69 6f 6e 20 69 66 0a 75 73  corruption if.us
0fd0: 65 64 20 62 79 20 74 77 6f 20 6f 72 20 6d 6f 72  ed by two or mor
0fe0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
0ff0: 63 74 69 6f 6e 73 20 61 74 20 74 68 65 20 73 61  ctions at the sa
1000: 6d 65 20 74 69 6d 65 2e 0a 50 72 6f 67 72 61 6d  me time..Program
1010: 6d 65 72 73 20 61 72 65 20 65 6e 63 6f 75 72 61  mers are encoura
1020: 67 65 64 20 74 6f 20 75 73 65 20 6f 6e 6c 79 20  ged to use only 
1030: 22 75 6e 69 78 22 20 6f 72 20 22 75 6e 69 78 2d  "unix" or "unix-
1040: 65 78 63 6c 22 20 75 6e 6c 65 73 73 0a 74 68 65  excl" unless.the
1050: 72 65 20 69 73 20 61 20 63 6f 6d 70 65 6c 6c 69  re is a compelli
1060: 6e 67 20 72 65 61 73 6f 6e 20 74 6f 20 64 6f 20  ng reason to do 
1070: 6f 74 68 65 72 77 69 73 65 2e 0a 3c 2f 70 3e 0a  otherwise..</p>.
1080: 0a 3c 68 32 3e 53 74 61 6e 64 61 72 64 20 57 69  .<h2>Standard Wi
1090: 6e 64 6f 77 73 20 56 46 53 65 73 3c 2f 68 32 3e  ndows VFSes</h2>
10a0: 0a 0a 0a 3c 70 3e 0a 57 69 6e 64 6f 77 73 20 62  ...<p>.Windows b
10b0: 75 69 6c 64 73 20 61 6c 73 6f 20 63 6f 6d 65 20  uilds also come 
10c0: 77 69 74 68 20 6d 75 6c 74 69 70 6c 65 20 62 75  with multiple bu
10d0: 69 6c 74 2d 69 6e 20 56 46 53 65 73 2e 20 20 54  ilt-in VFSes.  T
10e0: 68 65 20 64 65 66 61 75 6c 74 0a 57 69 6e 64 6f  he default.Windo
10f0: 77 73 20 56 46 53 20 69 73 20 63 61 6c 6c 65 64  ws VFS is called
1100: 20 22 77 69 6e 33 32 22 20 61 6e 64 20 69 73 20   "win32" and is 
1110: 75 73 65 64 20 69 6e 20 6d 6f 73 74 20 61 70 70  used in most app
1120: 6c 69 63 61 74 69 6f 6e 73 2e 0a 4f 74 68 65 72  lications..Other
1130: 20 56 46 53 65 73 20 74 68 61 74 20 6d 69 67 68   VFSes that migh
1140: 74 20 62 65 20 66 6f 75 6e 64 20 6f 6e 20 77 69  t be found on wi
1150: 6e 64 6f 77 73 20 62 75 69 6c 64 73 20 69 6e 63  ndows builds inc
1160: 6c 75 64 65 3a 0a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e  lude:.</p>..<ol>
1170: 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e 77 69 6e 33 32  .<li><p><b>win32
1180: 2d 6c 6f 6e 67 70 61 74 68 3c 2f 62 3e 20 2d 20  -longpath</b> - 
1190: 6c 69 6b 65 20 22 77 69 6e 33 32 22 20 65 78 63  like "win32" exc
11a0: 65 70 74 20 74 68 61 74 20 70 61 74 68 6e 61 6d  ept that pathnam
11b0: 65 73 20 63 61 6e 0a 20 20 20 20 20 20 20 20 20  es can.         
11c0: 20 62 65 20 75 70 20 74 6f 20 36 35 35 33 34 20   be up to 65534 
11d0: 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
11e0: 20 77 68 65 72 65 61 73 20 70 61 74 68 6e 61 6d   whereas pathnam
11f0: 65 73 20 6d 61 78 20 6f 75 74 20 61 74 0a 20 20  es max out at.  
1200: 20 20 20 20 20 20 20 20 31 30 34 30 20 62 79 74          1040 byt
1210: 65 73 20 69 6e 20 22 77 69 6e 33 32 22 2e 0a 3c  es in "win32"..<
1220: 6c 69 3e 3c 70 3e 3c 62 3e 77 69 6e 33 32 2d 6e  li><p><b>win32-n
1230: 6f 6e 65 3c 2f 62 3e 20 2d 20 61 6c 6c 20 66 69  one</b> - all fi
1240: 6c 65 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  le locking opera
1250: 74 69 6f 6e 73 20 61 72 65 20 6e 6f 2d 6f 70 73  tions are no-ops
1260: 2e 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e 77 69 6e 33  ..<li><p><b>win3
1270: 32 2d 6c 6f 6e 67 70 61 74 68 2d 6e 6f 6e 65 3c  2-longpath-none<
1280: 2f 62 3e 20 2d 20 63 6f 6d 62 69 6e 61 74 69 6f  /b> - combinatio
1290: 6e 20 6f 66 20 22 77 69 6e 33 32 2d 6c 6f 6e 67  n of "win32-long
12a0: 70 61 74 68 22 0a 20 20 20 20 20 20 20 20 20 20  path".          
12b0: 61 6e 64 20 22 77 69 6e 33 32 2d 6e 6f 6e 65 22  and "win32-none"
12c0: 20 2d 20 6c 6f 6e 67 20 70 61 74 68 6e 61 6d 65   - long pathname
12d0: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
12e0: 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 0a 20 20 20  and all lock.   
12f0: 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e         operation
1300: 73 20 61 72 65 20 6e 6f 2d 6f 70 73 2e 0a 3c 2f  s are no-ops..</
1310: 6f 6c 3e 0a 0a 3c 70 3e 41 73 20 77 69 74 68 20  ol>..<p>As with 
1320: 75 6e 69 78 2c 20 6d 6f 73 74 20 6f 66 20 74 68  unix, most of th
1330: 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20 76  e code for the v
1340: 61 72 69 6f 75 73 20 57 69 6e 64 6f 77 73 20 56  arious Windows V
1350: 46 53 65 73 20 69 73 20 73 68 61 72 65 64 2e 0a  FSes is shared..
1360: 0a 3c 68 32 3e 53 70 65 63 69 66 79 69 6e 67 20  .<h2>Specifying 
1370: 57 68 69 63 68 20 56 46 53 20 54 6f 20 55 73 65  Which VFS To Use
1380: 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 54 68 65 72 65  </h2>..<p>.There
1390: 20 69 73 20 61 6c 77 61 79 73 20 6f 6e 65 20 56   is always one V
13a0: 46 53 20 77 68 69 63 68 20 69 73 20 74 68 65 20  FS which is the 
13b0: 64 65 66 61 75 6c 74 20 56 46 53 2e 20 20 4f 6e  default VFS.  On
13c0: 20 75 6e 69 78 20 73 79 73 74 65 6d 73 2c 0a 74   unix systems,.t
13d0: 68 65 20 22 75 6e 69 78 22 20 56 46 53 20 63 6f  he "unix" VFS co
13e0: 6d 65 73 20 75 70 20 61 73 20 74 68 65 20 64 65  mes up as the de
13f0: 66 61 75 6c 74 20 61 6e 64 20 6f 6e 20 77 69 6e  fault and on win
1400: 64 6f 77 73 20 69 74 20 69 73 20 22 77 69 6e 33  dows it is "win3
1410: 32 22 2e 0a 49 66 20 6e 6f 20 6f 74 68 65 72 20  2"..If no other 
1420: 61 63 74 69 6f 6e 73 20 61 72 65 20 74 61 6b 65  actions are take
1430: 6e 2c 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  n, new database 
1440: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 69 6c 6c  connections will
1450: 20 6d 61 6b 65 20 75 73 65 0a 6f 66 20 74 68 65   make use.of the
1460: 20 64 65 66 61 75 6c 74 20 56 46 53 2e 0a 3c 2f   default VFS..</
1470: 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 64 65 66 61  p>..<p>.The defa
1480: 75 6c 74 20 56 46 53 20 63 61 6e 20 62 65 20 63  ult VFS can be c
1490: 68 61 6e 67 65 64 20 62 79 20 72 65 67 69 73 74  hanged by regist
14a0: 65 72 69 6e 67 20 6f 72 20 72 65 2d 72 65 67 69  ering or re-regi
14b0: 73 74 65 72 69 6e 67 20 74 68 65 0a 56 46 53 20  stering the.VFS 
14c0: 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
14d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
14e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  )] interface wit
14f0: 68 20 61 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  h a second param
1500: 65 74 65 72 0a 6f 66 20 31 2e 20 20 48 65 6e 63  eter.of 1.  Henc
1510: 65 2c 20 69 66 20 61 20 28 75 6e 69 78 29 20 70  e, if a (unix) p
1520: 72 6f 63 65 73 73 20 77 61 6e 74 73 20 74 6f 20  rocess wants to 
1530: 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 22  always use the "
1540: 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 20 56 46 53  unix-nolock" VFS
1550: 20 0a 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 75   .in place of "u
1560: 6e 69 78 22 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  nix", the follow
1570: 69 6e 67 20 63 6f 64 65 20 77 6f 75 6c 64 20 77  ing code would w
1580: 6f 72 6b 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  ork:.</p>..<bloc
1590: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 73 71 6c  kquote><pre>.sql
15a0: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
15b0: 72 28 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69  r(sqlite3_vfs_fi
15c0: 6e 64 28 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  nd("unix-nolock"
15d0: 29 2c 20 31 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62  ), 1);.</pre></b
15e0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a  lockquote>..<p>.
15f0: 41 6e 20 61 6c 74 65 72 6e 61 74 65 20 56 46 53  An alternate VFS
1600: 20 63 61 6e 20 61 6c 73 6f 20 62 65 20 73 70 65   can also be spe
1610: 63 69 66 69 65 64 20 61 73 20 74 68 65 20 34 74  cified as the 4t
1620: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1630: 68 65 0a 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he.[sqlite3_open
1640: 5f 76 32 28 29 5d 20 66 75 6e 63 74 69 6f 6e 2e  _v2()] function.
1650: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 3c    For example:.<
1660: 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  /p>..<blockquote
1670: 3e 3c 70 72 65 3e 0a 69 6e 74 20 72 63 20 3d 20  ><pre>.int rc = 
1680: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1690: 22 64 65 6d 6f 2e 64 62 22 2c 20 26 64 62 2c 20  "demo.db", &db, 
16a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
16b0: 57 52 49 54 45 2c 20 22 75 6e 69 78 2d 6e 6f 6c  WRITE, "unix-nol
16c0: 6f 63 6b 22 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62  ock");.</pre></b
16d0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a  lockquote>..<p>.
16e0: 46 69 6e 61 6c 6c 79 2c 20 69 66 20 5b 55 52 49  Finally, if [URI
16f0: 20 66 69 6c 65 6e 61 6d 65 73 5d 20 68 61 76 65   filenames] have
1700: 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 2c 20 74   been enabled, t
1710: 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
1720: 69 76 65 0a 56 46 53 20 63 61 6e 20 62 65 20 73  ive.VFS can be s
1730: 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 20 74  pecified using t
1740: 68 65 20 22 76 66 73 3d 22 20 70 61 72 61 6d 65  he "vfs=" parame
1750: 74 65 72 20 6f 6e 20 74 68 65 20 55 52 49 2e 20  ter on the URI. 
1760: 20 54 68 69 73 20 74 65 63 68 6e 69 71 75 65 0a   This technique.
1770: 77 6f 72 6b 73 20 77 69 74 68 20 5b 73 71 6c 69  works with [sqli
1780: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1790: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
17a0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
17b0: 32 28 29 5d 2c 20 61 6e 64 0a 77 68 65 6e 20 61  2()], and.when a
17c0: 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 69 73   new database is
17d0: 20 5b 41 54 54 41 43 48 5d 2d 65 64 20 74 6f 20   [ATTACH]-ed to 
17e0: 61 6e 20 65 78 69 73 74 69 6e 67 20 64 61 74 61  an existing data
17f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1800: 0a 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a 3c 2f  .For example:.</
1810: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
1820: 3c 70 72 65 3e 0a 41 54 54 41 43 48 20 27 66 69  <pre>.ATTACH 'fi
1830: 6c 65 3a 64 65 6d 6f 32 2e 64 62 3f 76 66 73 3d  le:demo2.db?vfs=
1840: 75 6e 69 78 2d 6e 6f 6e 65 27 20 41 53 20 64 65  unix-none' AS de
1850: 6d 6f 32 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  mo2;.</pre></blo
1860: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 0a 54 68  ckquote>..<p>.Th
1870: 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20  e VFS specified 
1880: 62 79 20 61 20 55 52 49 20 68 61 73 20 74 68 65  by a URI has the
1890: 20 68 69 67 68 65 73 74 20 70 72 69 6f 72 69 74   highest priorit
18a0: 79 2e 20 20 41 66 74 65 72 20 74 68 61 74 20 63  y.  After that c
18b0: 6f 6d 65 73 0a 61 20 56 46 53 20 73 70 65 63 69  omes.a VFS speci
18c0: 66 69 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  fied as the four
18d0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
18e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
18f0: 29 5d 2e 20 20 54 68 65 0a 64 65 66 61 75 6c 74  )].  The.default
1900: 20 56 46 53 20 69 73 20 75 73 65 64 20 69 66 20   VFS is used if 
1910: 6e 6f 20 56 46 53 20 69 73 20 73 70 65 63 69 66  no VFS is specif
1920: 69 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 3c  ied otherwise..<
1930: 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61  /p>..<tcl>hd_fra
1940: 67 6d 65 6e 74 20 73 68 69 6d 20 7b 56 46 53 20  gment shim {VFS 
1950: 73 68 69 6d 73 7d 20 7b 73 68 69 6d 73 7d 20 7b  shims} {shims} {
1960: 56 46 53 20 73 68 69 6d 7d 3c 2f 74 63 6c 3e 0a  VFS shim}</tcl>.
1970: 3c 68 32 3e 56 46 53 20 53 68 69 6d 73 3c 2f 68  <h2>VFS Shims</h
1980: 32 3e 0a 0a 3c 70 3e 0a 46 72 6f 6d 20 74 68 65  2>..<p>.From the
1990: 20 70 6f 69 6e 74 20 6f 66 20 76 69 65 77 20 6f   point of view o
19a0: 66 20 74 68 65 20 75 70 70 65 72 73 20 6c 61 79  f the uppers lay
19b0: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
19c0: 65 20 73 74 61 63 6b 2c 20 65 61 63 68 0a 6f 70  e stack, each.op
19d0: 65 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  en database file
19e0: 20 75 73 65 73 20 65 78 61 63 74 6c 79 20 6f 6e   uses exactly on
19f0: 65 20 56 46 53 2e 0a 42 75 74 20 69 6e 20 70 72  e VFS..But in pr
1a00: 61 63 74 69 63 65 2c 20 61 20 70 61 72 74 69 63  actice, a partic
1a10: 75 6c 61 72 20 56 46 53 20 6d 69 67 68 74 0a 6a  ular VFS might.j
1a20: 75 73 74 20 62 65 20 61 20 74 68 69 6e 20 77 72  ust be a thin wr
1a30: 61 70 70 65 72 20 61 72 6f 75 6e 64 20 61 6e 6f  apper around ano
1a40: 74 68 65 72 20 56 46 53 20 74 68 61 74 20 64 6f  ther VFS that do
1a50: 65 73 20 74 68 65 20 72 65 61 6c 20 77 6f 72 6b  es the real work
1a60: 2e 0a 57 65 20 63 61 6c 6c 20 61 20 77 72 61 70  ..We call a wrap
1a70: 70 65 72 20 56 46 53 20 61 20 22 73 68 69 6d 22  per VFS a "shim"
1a80: 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 41 20 73 69  ..</p>..<p>.A si
1a90: 6d 70 6c 65 20 65 78 61 6d 70 6c 65 20 6f 66 20  mple example of 
1aa0: 61 20 73 68 69 6d 20 69 73 20 74 68 65 20 22 76  a shim is the "v
1ab0: 66 73 74 72 61 63 65 22 20 56 46 53 2e 20 20 54  fstrace" VFS.  T
1ac0: 68 69 73 20 69 73 20 61 20 56 46 53 0a 28 69 6d  his is a VFS.(im
1ad0: 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74 68 65  plemented in the
1ae0: 20 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71   .[http://www.sq
1af0: 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64 6f 63  lite.org/src/doc
1b00: 2f 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73 74 5f  /trunk/src/test_
1b10: 76 66 73 74 72 61 63 65 2e 63 20 7c 20 74 65 73  vfstrace.c | tes
1b20: 74 5f 76 66 73 74 72 61 63 65 2e 63 5d 0a 73 6f  t_vfstrace.c].so
1b30: 75 72 63 65 20 66 69 6c 65 29 20 74 68 61 74 20  urce file) that 
1b40: 77 72 69 74 65 73 20 61 20 6d 65 73 73 61 67 65  writes a message
1b50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1b60: 20 65 61 63 68 20 56 46 53 20 6d 65 74 68 6f 64   each VFS method
1b70: 20 63 61 6c 6c 0a 69 6e 74 6f 20 61 20 6c 6f 67   call.into a log
1b80: 20 66 69 6c 65 2c 20 74 68 65 6e 20 70 61 73 73   file, then pass
1b90: 65 73 20 63 6f 6e 74 72 6f 6c 20 6f 66 66 20 74  es control off t
1ba0: 6f 20 61 6e 6f 74 68 65 72 20 56 46 53 20 74 6f  o another VFS to
1bb0: 20 64 6f 20 74 68 65 20 61 63 74 75 61 6c 0a 77   do the actual.w
1bc0: 6f 72 6b 2e 0a 3c 2f 70 3e 0a 0a 3c 68 32 3e 4f  ork..</p>..<h2>O
1bd0: 74 68 65 72 20 45 78 61 6d 70 6c 65 20 56 46 53  ther Example VFS
1be0: 65 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 0a 54 68 65  es</h2>..<p>.The
1bf0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 6f   following are o
1c00: 74 68 65 72 20 56 46 53 20 69 6d 70 6c 65 6d 65  ther VFS impleme
1c10: 6e 74 61 74 69 6f 6e 73 20 61 76 61 69 6c 61 62  ntations availab
1c20: 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
1c30: 0a 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74  .SQLite source t
1c40: 72 65 65 3a 0a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a  ree:.</p>..<ul>.
1c50: 3c 6c 69 3e 3c 70 3e 0a 5b 68 74 74 70 3a 2f 2f  <li><p>.[http://
1c60: 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73  www.sqlite.org/s
1c70: 72 63 2f 66 69 6c 65 2f 65 78 74 2f 6d 69 73 63  rc/file/ext/misc
1c80: 2f 61 70 70 65 6e 64 76 66 73 2e 63 20 7c 20 61  /appendvfs.c | a
1c90: 70 70 65 6e 64 76 66 73 2e 63 5d 20 2d 0a 54 68  ppendvfs.c] -.Th
1ca0: 69 73 20 56 46 53 20 61 6c 6c 6f 77 73 20 61 6e  is VFS allows an
1cb0: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1cc0: 20 74 6f 20 62 65 20 61 70 70 65 6e 64 65 64 20   to be appended 
1cd0: 74 6f 20 74 68 65 20 65 6e 64 20 6f 66 20 73 6f  to the end of so
1ce0: 6d 65 0a 6f 74 68 65 72 20 66 69 6c 65 2e 20 20  me.other file.  
1cf0: 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
1d00: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
1d10: 6f 20 61 70 70 65 6e 64 20 61 6e 20 53 51 4c 69  o append an SQLi
1d20: 74 65 20 64 61 74 61 62 61 73 65 0a 6f 6e 74 6f  te database.onto
1d30: 20 74 68 65 20 65 6e 64 20 6f 66 20 61 6e 20 65   the end of an e
1d40: 78 65 63 75 74 61 62 6c 65 20 73 75 63 68 20 74  xecutable such t
1d50: 68 61 74 20 74 68 65 20 65 78 65 63 75 74 61 62  hat the executab
1d60: 6c 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 0a  le where it can.
1d70: 74 68 65 6e 20 62 65 20 65 61 73 69 6c 79 20 6c  then be easily l
1d80: 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 65 78  ocated by the ex
1d90: 65 63 75 74 61 62 6c 65 20 77 68 65 6e 20 6e 65  ecutable when ne
1da0: 65 64 65 64 2e 20 20 54 68 65 0a 5b 63 6f 6d 6d  eded.  The.[comm
1db0: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 5d 20  and-line shell] 
1dc0: 77 69 6c 6c 20 75 73 65 20 74 68 69 73 20 56 46  will use this VF
1dd0: 53 20 69 66 20 6c 61 75 6e 63 68 65 64 20 77 69  S if launched wi
1de0: 74 68 20 74 68 65 20 2d 2d 61 70 70 65 6e 64 0a  th the --append.
1df0: 6f 70 74 69 6f 6e 2e 0a 0a 3c 6c 69 3e 3c 70 3e  option...<li><p>
1e00: 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  .[http://www.sql
1e10: 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64 6f 63 2f  ite.org/src/doc/
1e20: 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73 74 5f 64  trunk/src/test_d
1e30: 65 6d 6f 76 66 73 2e 63 20 7c 20 74 65 73 74 5f  emovfs.c | test_
1e40: 64 65 6d 6f 76 66 73 2e 63 5d 20 2d 20 0a 54 68  demovfs.c] - .Th
1e50: 69 73 20 66 69 6c 65 20 69 6d 70 6c 65 6d 65 6e  is file implemen
1e60: 74 73 20 61 20 76 65 72 79 20 73 69 6d 70 6c 65  ts a very simple
1e70: 20 56 46 53 20 6e 61 6d 65 64 20 22 64 65 6d 6f   VFS named "demo
1e80: 22 20 74 68 61 74 20 75 73 65 73 20 50 4f 53 49  " that uses POSI
1e90: 58 20 0a 66 75 6e 63 74 69 6f 6e 73 20 73 75 63  X .functions suc
1ea0: 68 20 61 73 0a 6f 70 65 6e 28 29 2c 20 72 65 61  h as.open(), rea
1eb0: 64 28 29 2c 20 77 72 69 74 65 28 29 2c 20 66 73  d(), write(), fs
1ec0: 79 6e 63 28 29 2c 20 63 6c 6f 73 65 28 29 2c 20  ync(), close(), 
1ed0: 66 73 79 6e 63 28 29 2c 20 73 6c 65 65 70 28 29  fsync(), sleep()
1ee0: 2c 20 74 69 6d 65 28 29 2c 0a 61 6e 64 20 73 6f  , time(),.and so
1ef0: 20 66 6f 72 74 68 2e 20 20 54 68 69 73 20 56 46   forth.  This VF
1f00: 53 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  S only works on 
1f10: 75 6e 69 78 20 73 79 73 74 65 6d 73 2e 20 20 42  unix systems.  B
1f20: 75 74 20 69 74 20 69 73 20 6e 6f 74 0a 69 6e 74  ut it is not.int
1f30: 65 6e 64 65 64 20 61 73 20 61 20 72 65 70 6c 61  ended as a repla
1f40: 63 65 6d 65 6e 74 20 66 6f 72 20 74 68 65 20 73  cement for the s
1f50: 74 61 6e 64 61 72 64 20 22 75 6e 69 78 22 20 56  tandard "unix" V
1f60: 46 53 20 75 73 65 64 20 62 79 20 64 65 66 61 75  FS used by defau
1f70: 6c 74 0a 6f 6e 20 75 6e 69 78 20 70 6c 61 74 66  lt.on unix platf
1f80: 6f 72 6d 73 2e 20 20 54 68 65 20 22 64 65 6d 6f  orms.  The "demo
1f90: 22 20 56 46 53 20 69 73 20 64 65 6c 69 62 65 72  " VFS is deliber
1fa0: 61 74 65 6c 79 20 6b 65 70 74 20 76 65 72 79 20  ately kept very 
1fb0: 73 69 6d 70 6c 65 0a 73 6f 20 74 68 61 74 20 69  simple.so that i
1fc0: 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  t can be used as
1fd0: 20 61 20 6c 65 61 72 6e 69 6e 67 20 61 69 64 20   a learning aid 
1fe0: 6f 72 20 61 73 20 74 65 6d 70 6c 61 74 65 20 66  or as template f
1ff0: 6f 72 20 62 75 69 6c 64 69 6e 67 0a 6f 74 68 65  or building.othe
2000: 72 20 56 46 53 65 73 20 6f 72 20 66 6f 72 20 70  r VFSes or for p
2010: 6f 72 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  orting SQLite to
2020: 20 6e 65 77 20 6f 70 65 72 61 74 69 6e 67 20 73   new operating s
2030: 79 73 74 65 6d 73 2e 0a 0a 3c 6c 69 3e 3c 70 3e  ystems...<li><p>
2040: 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  .[http://www.sql
2050: 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64 6f 63 2f  ite.org/src/doc/
2060: 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73 74 5f 71  trunk/src/test_q
2070: 75 6f 74 61 2e 63 20 7c 20 74 65 73 74 5f 71 75  uota.c | test_qu
2080: 6f 74 61 2e 63 5d 20 2d 20 0a 54 68 69 73 20 66  ota.c] - .This f
2090: 69 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61  ile implements a
20a0: 20 73 68 69 6d 20 63 61 6c 6c 65 64 20 22 71 75   shim called "qu
20b0: 6f 74 61 22 20 74 68 61 74 20 65 6e 66 6f 72 63  ota" that enforc
20c0: 65 73 20 63 75 6d 75 6c 61 74 69 76 65 0a 66 69  es cumulative.fi
20d0: 6c 65 20 73 69 7a 65 20 6c 69 6d 69 74 73 20 6f  le size limits o
20e0: 6e 20 61 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  n a collection o
20f0: 66 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  f database files
2100: 2e 20 20 41 6e 20 61 75 78 69 6c 69 61 72 79 0a  .  An auxiliary.
2110: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
2120: 64 20 74 6f 20 64 65 66 69 6e 65 20 22 71 75 6f  d to define "quo
2130: 74 61 20 67 72 6f 75 70 73 22 2e 20 20 41 20 71  ta groups".  A q
2140: 75 6f 74 61 20 67 72 6f 75 70 20 69 73 20 61 0a  uota group is a.
2150: 73 65 74 20 6f 66 20 66 69 6c 65 73 20 28 64 61  set of files (da
2160: 74 61 62 61 73 65 20 66 69 6c 65 73 2c 20 6a 6f  tabase files, jo
2170: 75 72 6e 61 6c 73 2c 20 61 6e 64 20 74 65 6d 70  urnals, and temp
2180: 6f 72 61 72 79 20 66 69 6c 65 73 29 20 77 68 6f  orary files) who
2190: 73 65 0a 6e 61 6d 65 73 20 61 6c 6c 20 6d 61 74  se.names all mat
21a0: 63 68 20 61 20 5b 47 4c 4f 42 5d 20 70 61 74 74  ch a [GLOB] patt
21b0: 65 72 6e 2e 20 20 54 68 65 20 73 75 6d 20 6f 66  ern.  The sum of
21c0: 20 74 68 65 20 73 69 7a 65 73 20 6f 66 20 61 6c   the sizes of al
21d0: 6c 20 66 69 6c 65 73 0a 69 6e 20 65 61 63 68 20  l files.in each 
21e0: 71 75 6f 74 61 20 67 72 6f 75 70 20 69 73 20 74  quota group is t
21f0: 72 61 63 6b 65 64 2c 20 61 6e 64 20 69 66 20 74  racked, and if t
2200: 68 61 74 20 73 75 6d 20 65 78 63 65 65 64 73 20  hat sum exceeds 
2210: 61 20 74 68 72 65 73 68 6f 6c 64 0a 64 65 66 69  a threshold.defi
2220: 6e 65 64 20 66 6f 72 20 74 68 65 20 71 75 6f 74  ned for the quot
2230: 61 20 67 72 6f 75 70 2c 20 61 20 63 61 6c 6c 62  a group, a callb
2240: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ack function is 
2250: 69 6e 76 6f 6b 65 64 2e 20 20 54 68 61 74 0a 63  invoked.  That.c
2260: 61 6c 6c 62 61 63 6b 20 63 61 6e 20 65 69 74 68  allback can eith
2270: 65 72 20 69 6e 63 72 65 61 73 65 20 74 68 65 20  er increase the 
2280: 74 68 72 65 73 68 6f 6c 64 20 6f 72 20 63 61 75  threshold or cau
2290: 73 65 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  se the operation
22a0: 0a 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65  .that would have
22b0: 20 65 78 63 65 65 64 65 64 20 74 68 65 20 71 75   exceeded the qu
22c0: 6f 74 61 20 74 6f 20 66 61 69 6c 20 77 69 74 68  ota to fail with
22d0: 20 61 6e 20 0a 5b 53 51 4c 49 54 45 5f 46 55 4c   an .[SQLITE_FUL
22e0: 4c 5d 20 65 72 72 6f 72 2e 20 20 4f 6e 65 20 6f  L] error.  One o
22f0: 66 20 74 68 65 20 75 73 65 73 20 6f 66 20 74 68  f the uses of th
2300: 69 73 20 73 68 69 6d 20 69 73 20 75 73 65 64 20  is shim is used 
2310: 74 6f 20 65 6e 66 6f 72 63 65 20 0a 72 65 73 6f  to enforce .reso
2320: 75 72 63 65 20 6c 69 6d 69 74 73 20 6f 6e 20 61  urce limits on a
2330: 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 62  pplication datab
2340: 61 73 65 73 20 69 6e 20 46 69 72 65 66 6f 78 2e  ases in Firefox.
2350: 0a 0a 3c 6c 69 3e 3c 70 3e 0a 5b 68 74 74 70 3a  ..<li><p>.[http:
2360: 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67  //www.sqlite.org
2370: 2f 73 72 63 2f 64 6f 63 2f 74 72 75 6e 6b 2f 73  /src/doc/trunk/s
2380: 72 63 2f 74 65 73 74 5f 6d 75 6c 74 69 70 6c 65  rc/test_multiple
2390: 78 2e 63 20 7c 20 74 65 73 74 5f 6d 75 6c 74 69  x.c | test_multi
23a0: 70 6c 65 78 2e 63 5d 20 2d 20 0a 54 68 69 73 20  plex.c] - .This 
23b0: 66 69 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  file implements 
23c0: 61 20 73 68 69 6d 20 74 68 61 74 20 61 6c 6c 6f  a shim that allo
23d0: 77 73 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ws database file
23e0: 73 20 74 6f 20 65 78 63 65 65 64 20 74 68 65 0a  s to exceed the.
23f0: 6d 61 78 69 6d 75 6d 20 66 69 6c 65 20 73 69 7a  maximum file siz
2400: 65 20 6f 66 20 74 68 65 20 75 6e 64 65 72 6c 79  e of the underly
2410: 69 6e 67 20 66 69 6c 65 73 79 73 74 65 6d 2e 20  ing filesystem. 
2420: 20 54 68 69 73 20 73 68 69 6d 20 70 72 65 73 65   This shim prese
2430: 6e 74 73 0a 61 6e 20 69 6e 74 65 72 66 61 63 65  nts.an interface
2440: 20 74 6f 20 74 68 65 20 75 70 70 65 72 20 73 69   to the upper si
2450: 78 20 6c 61 79 65 72 73 20 6f 66 20 53 51 4c 69  x layers of SQLi
2460: 74 65 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74  te that makes it
2470: 20 6c 6f 6f 6b 20 6c 69 6b 65 0a 76 65 72 79 20   look like.very 
2480: 6c 61 72 67 65 20 66 69 6c 65 73 20 61 72 65 20  large files are 
2490: 62 65 69 6e 67 20 75 73 65 64 2c 20 77 68 65 6e  being used, when
24a0: 20 69 6e 20 72 65 61 6c 69 74 79 20 65 61 63 68   in reality each
24b0: 20 73 75 63 68 20 6c 61 72 67 65 20 66 69 6c 65   such large file
24c0: 0a 69 73 20 73 70 6c 69 74 20 75 70 20 69 6e 74  .is split up int
24d0: 6f 20 6d 61 6e 79 20 73 6d 61 6c 6c 65 72 20 66  o many smaller f
24e0: 69 6c 65 73 20 6f 6e 20 74 68 65 20 75 6e 64 65  iles on the unde
24f0: 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 2e 0a 54  rlying system..T
2500: 68 69 73 20 73 68 69 6d 20 68 61 73 20 62 65 65  his shim has bee
2510: 6e 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  n used, for exam
2520: 70 6c 65 2c 20 74 6f 20 61 6c 6c 6f 77 20 64 61  ple, to allow da
2530: 74 61 62 61 73 65 73 20 74 6f 20 67 72 6f 77 0a  tabases to grow.
2540: 6c 61 72 67 65 72 20 74 68 61 6e 20 32 20 67 69  larger than 2 gi
2550: 62 69 62 79 74 65 73 20 6f 6e 20 46 41 54 31 36  bibytes on FAT16
2560: 20 66 69 6c 65 73 79 73 74 65 6d 73 2e 0a 0a 3c   filesystems...<
2570: 6c 69 3e 3c 70 3e 0a 5b 68 74 74 70 3a 2f 2f 77  li><p>.[http://w
2580: 77 77 2e 73 71 6c 69 74 65 2e 6f 72 67 2f 73 72  ww.sqlite.org/sr
2590: 63 2f 64 6f 63 2f 74 72 75 6e 6b 2f 73 72 63 2f  c/doc/trunk/src/
25a0: 74 65 73 74 5f 6f 6e 65 66 69 6c 65 2e 63 20 7c  test_onefile.c |
25b0: 20 74 65 73 74 5f 6f 6e 65 66 69 6c 65 2e 63 5d   test_onefile.c]
25c0: 20 2d 20 0a 54 68 69 73 20 66 69 6c 65 20 69 6d   - .This file im
25d0: 70 6c 65 6d 65 6e 74 73 20 61 20 64 65 6d 6f 6e  plements a demon
25e0: 73 74 72 61 74 69 6f 6e 20 56 46 53 20 6e 61 6d  stration VFS nam
25f0: 65 64 20 22 66 73 22 20 74 68 61 74 20 73 68 6f  ed "fs" that sho
2600: 77 73 20 68 6f 77 20 53 51 4c 69 74 65 20 0a 63  ws how SQLite .c
2610: 61 6e 20 62 65 20 75 73 65 64 20 6f 6e 20 61 6e  an be used on an
2620: 20 65 6d 62 65 64 64 65 64 20 64 65 76 69 63 65   embedded device
2630: 20 74 68 61 74 20 6c 61 63 6b 73 20 61 20 66 69   that lacks a fi
2640: 6c 65 73 79 73 74 65 6d 2e 20 20 43 6f 6e 74 65  lesystem.  Conte
2650: 6e 74 20 69 73 0a 77 72 69 74 74 65 6e 20 64 69  nt is.written di
2660: 72 65 63 74 6c 79 20 74 6f 20 74 68 65 20 75 6e  rectly to the un
2670: 64 65 72 6c 79 69 6e 67 20 6d 65 64 69 61 2e 20  derlying media. 
2680: 20 41 20 56 46 53 20 64 65 72 69 76 65 64 20 66   A VFS derived f
2690: 72 6f 6d 20 74 68 69 73 0a 64 65 6d 6f 6e 73 74  rom this.demonst
26a0: 72 61 74 69 6f 6e 20 63 6f 64 65 20 63 6f 75 6c  ration code coul
26b0: 64 20 62 65 20 75 73 65 64 20 62 79 20 61 20 67  d be used by a g
26c0: 61 64 67 65 74 20 77 69 74 68 20 61 20 6c 69 6d  adget with a lim
26d0: 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 0a 66  ited amount of.f
26e0: 6c 61 73 68 20 6d 65 6d 6f 72 79 20 74 6f 20 6d  lash memory to m
26f0: 61 6b 65 20 53 51 4c 69 74 65 20 62 65 68 61 76  ake SQLite behav
2700: 65 20 61 73 20 74 68 65 20 66 69 6c 65 73 79 73  e as the filesys
2710: 74 65 6d 20 66 6f 72 20 74 68 65 20 66 6c 61 73  tem for the flas
2720: 68 20 6d 65 6d 6f 72 79 0a 6f 6e 20 74 68 65 20  h memory.on the 
2730: 64 65 76 69 63 65 2e 0a 0a 3c 6c 69 3e 3c 70 3e  device...<li><p>
2740: 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  .[http://www.sql
2750: 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64 6f 63 2f  ite.org/src/doc/
2760: 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73 74 5f 6a  trunk/src/test_j
2770: 6f 75 72 6e 61 6c 2e 63 20 7c 20 74 65 73 74 5f  ournal.c | test_
2780: 6a 6f 75 72 6e 61 6c 2e 63 5d 20 2d 20 0a 54 68  journal.c] - .Th
2790: 69 73 20 66 69 6c 65 20 69 6d 70 6c 65 6d 65 6e  is file implemen
27a0: 74 73 20 61 20 73 68 69 6d 20 75 73 65 64 20 64  ts a shim used d
27b0: 75 72 69 6e 67 20 53 51 4c 69 74 65 20 74 65 73  uring SQLite tes
27c0: 74 69 6e 67 20 74 68 61 74 20 76 65 72 69 66 69  ting that verifi
27d0: 65 73 20 74 68 61 74 0a 74 68 65 20 64 61 74 61  es that.the data
27e0: 62 61 73 65 20 61 6e 64 20 72 6f 6c 6c 62 61 63  base and rollbac
27f0: 6b 20 6a 6f 75 72 6e 61 6c 20 61 72 65 20 77 72  k journal are wr
2800: 69 74 74 65 6e 20 69 6e 20 74 68 65 20 63 6f 72  itten in the cor
2810: 72 65 63 74 20 6f 72 64 65 72 20 61 6e 64 0a 61  rect order and.a
2820: 72 65 20 22 73 79 6e 63 65 64 22 20 61 74 20 61  re "synced" at a
2830: 70 70 72 6f 70 72 69 61 74 65 20 74 69 6d 65 73  ppropriate times
2840: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 67 75 61   in order to gua
2850: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
2860: 64 61 74 61 62 61 73 65 0a 63 61 6e 20 72 65 63  database.can rec
2870: 6f 76 65 72 20 66 72 6f 6d 20 61 20 70 6f 77 65  over from a powe
2880: 72 20 6c 6f 73 65 20 61 72 65 20 68 61 72 64 20  r lose are hard 
2890: 72 65 73 65 74 20 61 74 20 61 6e 79 20 74 69 6d  reset at any tim
28a0: 65 2e 20 20 54 68 65 20 73 68 69 6d 0a 63 68 65  e.  The shim.che
28b0: 63 6b 73 20 73 65 76 65 72 61 6c 20 69 6e 76 61  cks several inva
28c0: 72 69 61 6e 74 73 20 6f 6e 20 74 68 65 20 6f 70  riants on the op
28d0: 65 72 61 74 69 6f 6e 20 6f 66 20 64 61 74 61 62  eration of datab
28e0: 61 73 65 73 20 61 6e 64 20 72 6f 6c 6c 62 61 63  ases and rollbac
28f0: 6b 0a 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 72  k.journals and r
2900: 61 69 73 65 73 20 65 78 63 65 70 74 69 6f 6e 73  aises exceptions
2910: 20 69 66 20 61 6e 79 20 6f 66 20 74 68 6f 73 65   if any of those
2920: 20 69 6e 76 61 72 69 61 6e 74 73 20 61 72 65 20   invariants are 
2930: 76 69 6f 6c 61 74 65 64 2e 0a 54 68 65 73 65 20  violated..These 
2940: 69 6e 76 61 72 69 61 6e 74 73 2c 20 69 6e 20 74  invariants, in t
2950: 75 72 6e 2c 20 61 73 73 75 72 65 20 74 68 61 74  urn, assure that
2960: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2970: 20 61 6c 77 61 79 73 20 72 65 63 6f 76 65 72 61   always recovera
2980: 62 6c 65 2e 0a 52 75 6e 6e 69 6e 67 20 61 20 6c  ble..Running a l
2990: 61 72 67 65 20 73 75 69 74 65 20 6f 66 20 74 65  arge suite of te
29a0: 73 74 20 63 61 73 65 73 20 75 73 69 6e 67 20 74  st cases using t
29b0: 68 69 73 20 73 68 69 6d 20 70 72 6f 76 69 64 65  his shim provide
29c0: 73 20 61 64 64 65 64 0a 61 73 73 75 72 61 6e 63  s added.assuranc
29d0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 64 61  e that SQLite da
29e0: 74 61 62 61 73 65 73 20 77 69 6c 6c 20 6e 6f 74  tabases will not
29f0: 20 62 65 20 64 61 6d 61 67 65 64 20 62 79 20 75   be damaged by u
2a00: 6e 65 78 70 65 63 74 65 64 0a 70 6f 77 65 72 20  nexpected.power 
2a10: 66 61 69 6c 75 72 65 73 20 6f 72 20 64 65 76 69  failures or devi
2a20: 63 65 20 72 65 73 65 74 73 2e 0a 0a 3c 6c 69 3e  ce resets...<li>
2a30: 3c 70 3e 0a 5b 68 74 74 70 3a 2f 2f 77 77 77 2e  <p>.[http://www.
2a40: 73 71 6c 69 74 65 2e 6f 72 67 2f 73 72 63 2f 64  sqlite.org/src/d
2a50: 6f 63 2f 74 72 75 6e 6b 2f 73 72 63 2f 74 65 73  oc/trunk/src/tes
2a60: 74 5f 76 66 73 2e 63 20 7c 20 74 65 73 74 5f 76  t_vfs.c | test_v
2a70: 66 73 2e 63 5d 20 2d 20 0a 54 68 69 73 20 66 69  fs.c] - .This fi
2a80: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 61 20  le implements a 
2a90: 73 68 69 6d 20 74 68 61 74 20 63 61 6e 20 62 65  shim that can be
2aa0: 20 75 73 65 64 20 74 6f 20 73 69 6d 75 6c 61 74   used to simulat
2ab0: 65 20 66 69 6c 65 73 79 73 74 65 6d 20 66 61 75  e filesystem fau
2ac0: 6c 74 73 2e 0a 54 68 69 73 20 73 68 69 6d 20 69  lts..This shim i
2ad0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
2ae0: 73 74 69 6e 67 20 74 6f 20 76 65 72 69 66 79 20  sting to verify 
2af0: 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 73 70  that SQLite resp
2b00: 6f 6e 73 65 73 20 73 61 6e 65 6c 79 0a 74 6f 20  onses sanely.to 
2b10: 68 61 72 64 77 61 72 65 20 6d 61 6c 66 75 6e 63  hardware malfunc
2b20: 74 69 6f 6e 73 20 6f 72 20 74 6f 20 6f 74 68 65  tions or to othe
2b30: 72 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  r error conditio
2b40: 6e 73 20 73 75 63 68 20 61 73 20 72 75 6e 6e 69  ns such as runni
2b50: 6e 67 20 6f 75 74 0a 6f 66 20 66 69 6c 65 73 79  ng out.of filesy
2b60: 73 74 65 6d 20 73 70 61 63 65 20 74 68 61 74 20  stem space that 
2b70: 61 72 65 20 64 69 66 66 69 63 75 6c 74 20 74 6f  are difficult to
2b80: 20 74 65 73 74 20 6f 6e 20 61 20 72 65 61 6c 20   test on a real 
2b90: 73 79 73 74 65 6d 2e 0a 3c 2f 75 6c 3e 0a 0a 3c  system..</ul>..<
2ba0: 70 3e 0a 54 68 65 72 65 20 61 72 65 20 6f 74 68  p>.There are oth
2bb0: 65 72 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  er VFS implement
2bc0: 61 74 69 6f 6e 73 20 62 6f 74 68 20 69 6e 20 74  ations both in t
2bd0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 73  he core SQLite s
2be0: 6f 75 72 63 65 20 63 6f 64 65 0a 6c 69 62 72 61  ource code.libra
2bf0: 72 79 20 61 6e 64 20 69 6e 20 61 76 61 69 6c 61  ry and in availa
2c00: 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  ble extensions. 
2c10: 20 54 68 65 20 6c 69 73 74 20 61 62 6f 76 65 20   The list above 
2c20: 69 73 20 6e 6f 74 20 6d 65 61 6e 74 20 74 6f 20  is not meant to 
2c30: 62 65 0a 65 78 68 61 75 73 74 69 76 65 20 62 75  be.exhaustive bu
2c40: 74 20 6d 65 72 65 6c 79 20 72 65 70 72 65 73 65  t merely represe
2c50: 6e 74 61 74 69 76 65 20 6f 66 20 74 68 65 20 6b  ntative of the k
2c60: 69 6e 64 73 20 6f 66 20 66 65 61 74 75 72 65 73  inds of features
2c70: 20 74 68 61 74 20 63 61 6e 0a 62 65 20 72 65 61   that can.be rea
2c80: 6c 69 7a 65 64 20 75 73 69 6e 67 20 74 68 65 20  lized using the 
2c90: 56 46 53 20 69 6e 74 65 72 66 61 63 65 2e 0a 3c  VFS interface..<
2ca0: 2f 70 3e 0a 0a 3c 68 31 3e 56 46 53 20 49 6d 70  /p>..<h1>VFS Imp
2cb0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 3c 2f 68 31  lementations</h1
2cc0: 3e 0a 0a 3c 70 3e 0a 41 20 6e 65 77 20 56 46 53  >..<p>.A new VFS
2cd0: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
2ce0: 62 79 20 73 75 62 63 6c 61 73 73 69 6e 67 20 74  by subclassing t
2cf0: 68 72 65 65 20 6f 62 6a 65 63 74 73 3a 0a 3c 2f  hree objects:.</
2d00: 70 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 5b 73 71  p>..<ul>.<li>[sq
2d10: 6c 69 74 65 33 5f 76 66 73 5d 0a 3c 6c 69 3e 5b  lite3_vfs].<li>[
2d20: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
2d30: 64 73 5d 0a 3c 6c 69 3e 5b 73 71 6c 69 74 65 33  ds].<li>[sqlite3
2d40: 5f 66 69 6c 65 5d 0a 3c 2f 75 6c 3e 0a 0a 3c 70  _file].</ul>..<p
2d50: 3e 0a 41 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  >.An [sqlite3_vf
2d60: 73 5d 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  s] object define
2d70: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2d80: 65 20 56 46 53 20 61 6e 64 20 74 68 65 20 63 6f  e VFS and the co
2d90: 72 65 0a 6d 65 74 68 6f 64 73 20 74 68 61 74 20  re.methods that 
2da0: 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 69 6e  implement the in
2db0: 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 6f  terface to the o
2dc0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2c  perating system,
2dd0: 20 73 75 63 68 0a 61 73 20 63 68 65 63 6b 69 6e   such.as checkin
2de0: 67 20 66 6f 72 20 65 78 69 73 74 65 6e 63 65 20  g for existence 
2df0: 6f 66 20 66 69 6c 65 73 2c 20 64 65 6c 65 74 69  of files, deleti
2e00: 6e 67 20 66 69 6c 65 73 2c 20 63 72 65 61 74 69  ng files, creati
2e10: 6e 67 20 66 69 6c 65 73 0a 61 6e 64 20 6f 70 65  ng files.and ope
2e20: 6e 69 6e 67 20 61 6e 64 20 66 6f 72 20 72 65 61  ning and for rea
2e30: 64 69 6e 67 20 61 6e 64 2f 6f 72 20 77 72 69 74  ding and/or writ
2e40: 69 6e 67 2c 20 63 6f 6e 76 65 72 74 69 6e 67 20  ing, converting 
2e50: 66 69 6c 65 6e 61 6d 65 73 0a 69 6e 74 6f 20 74  filenames.into t
2e60: 68 65 69 72 20 63 61 6e 6f 6e 69 63 61 6c 20 66  heir canonical f
2e70: 6f 72 6d 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  orm.  The [sqlit
2e80: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 61  e3_vfs] object a
2e90: 6c 73 6f 20 63 6f 6e 74 61 69 6e 73 0a 6d 65 74  lso contains.met
2ea0: 68 6f 64 73 20 66 6f 72 20 6f 62 74 61 69 6e 69  hods for obtaini
2eb0: 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 66 72  ng randomness fr
2ec0: 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
2ed0: 20 73 79 73 74 65 6d 2c 20 66 6f 72 0a 73 75 73   system, for.sus
2ee0: 70 65 6e 64 69 6e 67 20 61 20 70 72 6f 63 65 73  pending a proces
2ef0: 73 20 28 73 6c 65 65 70 69 6e 67 29 20 61 6e 64  s (sleeping) and
2f00: 20 66 6f 72 20 66 69 6e 64 69 6e 67 20 74 68 65   for finding the
2f10: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
2f20: 64 0a 74 69 6d 65 2e 0a 3c 2f 70 3e 0a 0a 3c 70  d.time..</p>..<p
2f30: 3e 0a 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  >.The [sqlite3_f
2f40: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
2f50: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
2f60: 69 6c 65 2e 0a 54 68 65 20 78 4f 70 65 6e 20 6d  ile..The xOpen m
2f70: 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
2f80: 33 5f 76 66 73 5d 20 63 6f 6e 73 74 72 75 63 74  3_vfs] construct
2f90: 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  s an [sqlite3_fi
2fa0: 6c 65 5d 0a 6f 62 6a 65 63 74 20 77 68 65 6e 20  le].object when 
2fb0: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 70 65 6e  the file is open
2fc0: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
2fd0: 33 5f 66 69 6c 65 5d 20 6b 65 65 70 73 20 74 72  3_file] keeps tr
2fe0: 61 63 6b 0a 6f 66 20 74 68 65 20 73 74 61 74 65  ack.of the state
2ff0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 77 68 69   of the file whi
3000: 6c 65 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2e  le it is opened.
3010: 0a 3c 2f 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 5b  .</p>..<p>.The [
3020: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
3030: 64 73 5d 20 6f 62 6a 65 63 74 20 68 6f 6c 64 73  ds] object holds
3040: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
3050: 64 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 77 69  d to interact.wi
3060: 74 68 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 2e  th an open file.
3070: 20 20 45 61 63 68 20 5b 73 71 6c 69 74 65 33 5f    Each [sqlite3_
3080: 66 69 6c 65 5d 20 63 6f 6e 74 61 69 6e 73 20 61  file] contains a
3090: 20 70 6f 69 6e 74 65 72 20 74 6f 20 0a 61 6e 20   pointer to .an 
30a0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
30b0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
30c0: 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   is appropriate 
30d0: 66 6f 72 20 74 68 65 20 66 69 6c 65 20 69 74 0a  for the file it.
30e0: 72 65 70 72 65 73 65 6e 74 73 2e 20 20 54 68 65  represents.  The
30f0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
3100: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 63 6f 6e  hods] object con
3110: 74 61 69 6e 73 20 6d 65 74 68 6f 64 73 20 74 6f  tains methods to
3120: 20 64 6f 0a 74 68 69 6e 67 73 20 73 75 63 68 20   do.things such 
3130: 61 73 20 72 65 61 64 20 61 6e 64 20 77 72 69 74  as read and writ
3140: 65 20 66 72 6f 6d 20 74 68 65 20 66 69 6c 65 2c  e from the file,
3150: 20 74 6f 20 74 72 75 6e 63 61 74 65 20 74 68 65   to truncate the
3160: 20 66 69 6c 65 2c 0a 74 6f 20 66 6c 75 73 68 20   file,.to flush 
3170: 61 6e 79 20 63 68 61 6e 67 65 73 20 74 6f 20 70  any changes to p
3180: 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67  ersistent storag
3190: 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  e, to find the s
31a0: 69 7a 65 20 6f 66 20 74 68 65 0a 66 69 6c 65 2c  ize of the.file,
31b0: 20 74 6f 20 6c 6f 63 6b 20 61 6e 64 20 75 6e 6c   to lock and unl
31c0: 6f 63 6b 20 74 68 65 20 66 69 6c 65 2c 20 61 6e  ock the file, an
31d0: 64 20 74 6f 20 63 6c 6f 73 65 20 66 69 6c 65 20  d to close file 
31e0: 61 6e 64 20 64 65 73 74 72 6f 79 0a 74 68 65 20  and destroy.the 
31f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
3200: 62 6a 65 63 74 2e 0a 3c 2f 70 3e 0a 0a 3c 70 3e  bject..</p>..<p>
3210: 0a 57 72 69 74 69 6e 67 20 74 68 65 20 63 6f 64  .Writing the cod
3220: 65 20 66 6f 72 20 61 20 6e 65 77 20 56 46 53 20  e for a new VFS 
3230: 69 6e 76 6f 6c 76 65 73 20 63 6f 6e 73 74 72 75  involves constru
3240: 63 74 69 6e 67 20 61 20 73 75 62 63 6c 61 73 73  cting a subclass
3250: 20 66 6f 72 0a 74 68 65 20 5b 73 71 6c 69 74 65   for.the [sqlite
3260: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 61 6e  3_vfs] object an
3270: 64 20 74 68 65 6e 20 72 65 67 69 73 74 65 72 69  d then registeri
3280: 6e 67 20 74 68 61 74 20 56 46 53 20 6f 62 6a 65  ng that VFS obje
3290: 63 74 20 75 73 69 6e 67 0a 61 20 63 61 6c 6c 20  ct using.a call 
32a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  to [sqlite3_vfs_
32b0: 72 65 67 69 73 74 65 72 28 29 5d 2e 20 20 54 68  register()].  Th
32c0: 65 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  e VFS implementa
32d0: 74 69 6f 6e 20 61 6c 73 6f 0a 70 72 6f 76 69 64  tion also.provid
32e0: 65 73 20 73 75 62 63 6c 61 73 73 65 73 20 66 6f  es subclasses fo
32f0: 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  r [sqlite3_file]
3300: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f   and [sqlite3_io
3310: 5f 6d 65 74 68 6f 64 73 5d 20 62 75 74 0a 74 68  _methods] but.th
3320: 6f 73 65 20 6f 62 6a 65 63 74 73 20 61 72 65 20  ose objects are 
3330: 6e 6f 74 20 72 65 67 69 73 74 65 72 65 64 20 64  not registered d
3340: 69 72 65 63 74 6c 79 20 77 69 74 68 20 53 51 4c  irectly with SQL
3350: 69 74 65 2e 20 20 49 6e 73 74 65 61 64 2c 20 74  ite.  Instead, t
3360: 68 65 0a 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he.[sqlite3_file
3370: 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 74 75  ] object is retu
3380: 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 4f  rned from the xO
3390: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 0a 5b 73  pen method of.[s
33a0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 61 6e 64 20  qlite3_vfs] and 
33b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
33c0: 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 73  e] object points
33d0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 0a   to an instance.
33e0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
33f0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
3400: 63 74 2e 0a 3c 2f 70 3e 0a                       ct..</p>.