Documentation Source Text

Check-in [26da8bcd0b]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add definitions for the "atomic-write" "safe-append" and "sequential-write" VFS properties to fileio.html.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 26da8bcd0b506a2ac75c493bf766bfa0989547a7
User & Date: dan 2008-07-29 16:42:12
Context
2008-07-30
09:00
Add a better overview to fileio.in. check-in: f0560b2aa4 user: dan tags: trunk
2008-07-29
16:42
Add definitions for the "atomic-write" "safe-append" and "sequential-write" VFS properties to fileio.html. check-in: 26da8bcd0b user: dan tags: trunk
2008-07-28
15:01
Start enumerating the assumptions sqlite makes related to the state of the file system following a power failure or OS crash. check-in: ac2c5476d0 user: dan tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to images/fileformat/rtdocs.css.

40
41
42
43
44
45
46
47


48
49
50
51
52
53
54
    text-align:left;
    border-bottom: solid 1px #444444;
    padding: 0.2em 1ex;
  }
  .striped td, #glossary td { vertical-align: top }
  .striped td, #glossary td { padding: 0.2em 1ex; }

  .spacedlist li { margin-top 0.5em ; margin-bottom: 0.5em }



  /* Style for "todo" notes. These are represented by markup like: 
  **
  **     <span class=todo>Fix this bit!</span>
  **     <p class=todo>Longer todo note.</p>
  */
  .todo        { color: #AA3333 ; font-style : italic }







|
>
>







40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
    text-align:left;
    border-bottom: solid 1px #444444;
    padding: 0.2em 1ex;
  }
  .striped td, #glossary td { vertical-align: top }
  .striped td, #glossary td { padding: 0.2em 1ex; }

  .spacedlist li { margin-top: 0.5em ; margin-bottom: 0.5em }

  li p { margin: 1em auto ; padding: 0 }

  /* Style for "todo" notes. These are represented by markup like: 
  **
  **     <span class=todo>Fix this bit!</span>
  **     <p class=todo>Longer todo note.</p>
  */
  .todo        { color: #AA3333 ; font-style : italic }

Changes to pages/fileio.in.

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
...
204
205
206
207
208
209
210
211
212







213









































214
215
216
217
218
219
220
      that the updated data has reached the persistent storage media, until
      after it has successfully <i>synced</i> the corresponding file by
      invoking the VFS xSync() method. <i>Syncing</i> a file causes all
      modifications to the file up until that point to be committed to
      persistent storage.

    <p>
      Based on the above, SQLite usually uses an internal model of the
      file-system whereby any sector of a file written to is considered to be
      in a transient state until after the file has been successfully 
      <i>synced</i>. Should a power or system failure occur while a sector 
      is in a transient state, it is impossible to predict its contents
      following recovery. It may be written correctly, not written at all,
      overwritten with random data, or any combination thereof.

................................................................................
      corrupted following a power or system failure is a very pessimistic
      approach. Some modern systems provide more sophisticated guarantees
      than this. SQLite allows the VFS implementation to specify at runtime
      that the current platform supports one or more of the following 
      properties:

    <ul>
      <li>The <b>safe-append</b> property. Details...
      <li>The <b>sequential-write</b> property. Details...







      <li>The <b>atomic-write</b> property. Details...









































    </ul>

    <h3>Details</h3>

    <p>
      This section describes how the assumptions presented in the parent
      section apply to the individual API functions and operations provided 







|







 







|
|
>
>
>
>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
...
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
      that the updated data has reached the persistent storage media, until
      after it has successfully <i>synced</i> the corresponding file by
      invoking the VFS xSync() method. <i>Syncing</i> a file causes all
      modifications to the file up until that point to be committed to
      persistent storage.

    <p>
      Based on the above, SQLite is designed around a model of the
      file-system whereby any sector of a file written to is considered to be
      in a transient state until after the file has been successfully 
      <i>synced</i>. Should a power or system failure occur while a sector 
      is in a transient state, it is impossible to predict its contents
      following recovery. It may be written correctly, not written at all,
      overwritten with random data, or any combination thereof.

................................................................................
      corrupted following a power or system failure is a very pessimistic
      approach. Some modern systems provide more sophisticated guarantees
      than this. SQLite allows the VFS implementation to specify at runtime
      that the current platform supports one or more of the following 
      properties:

    <ul>
      <li><p>The <b>safe-append</b> property. If a system supports the
          <i>safe-append</i> property, it means that when a file is extended
          the new data is written to the persistent media before the size
          of the file itself is updated. This guarantees that if a failure
          occurs after a file has been extended, following recovery 
          the write operations that extended the file will appear to have 
          succeeded or not occurred at all. It is not possible for invalid
          or garbage data to appear in the extended region of the file.

      <li><p>The <b>atomic-write</b> property. A system that supports this
          property also specifies the size or sizes of the blocks that it
          is capable of writing. Valid sizes are powers of two greater than
          512. If a write operation modifies a block of <i>n</i> bytes,
          where <i>n</i> is one of the block sizes for which <i>atomic-write</i>
          is supported, then it is impossible for an aligned write of <i>n</i>
          bytes to cause data corruption. If a failure occurs after such 
	  a write operation and before the applicable file handle is
          <i>synced</i>, then following recovery it will appear as if the
          write operation succeeded or did not take place at all. It is not
          possible that only part of the data specified by the write operation
          was written to persistent media, nor is it possible for any content
          of the sectors spanned by the write operation to be replaced with
          garbage data, as it is normally assumed to be.

      <li><p>The <b>sequential-write</b> property. A system that supports the
          <i>sequential-write</i> property guarantees that the various write
          operations on files within the same file-system are written to the
          persistent media in the same order that they are performed by the
          application and that each operation is concluded before the next
          is begun. If a system supports the <i>sequential-write</i> 
          property, then the model used to determine the possible states of
          the file-system following a failure is different. 

          <p>If a system supports <i>sequential-write</i> it is assumed that 
          <i>syncing</i> any file within the file system flushes all write
          operations on all files (not just the <i>synced</i> file) to
          the persistent media. If a failure does occur, it is not known
          whether or not any of the write operations performed by SQLite 
          since the last time a file was <i>synced</i>. SQLite is able to
          assume that if the write operations of unknown status are arranged
          in the order that they occured:
          <ol> 
            <li> the first <i>n</i> operations will have been executed 
                 successfully,
            <li> the next operation puts all device sectors that it modifies
                 into the transient state, so that following recovery each
		 sector may be partially written, completely written, not
                 written at all or populated with garbage data,
            <li> the remaining operations will not have had any effect on
                 the contents of the file-system.
          </ol> 
    </ul>

    <h3>Details</h3>

    <p>
      This section describes how the assumptions presented in the parent
      section apply to the individual API functions and operations provided