/ Check-in [83077ec8]
Login

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

Overview
Comment:Additional documentation on the new VFS interface. No changes to code.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | batch-atomic-write
Files: files | file ages | folders
SHA3-256: 83077ec8b5804e6c709fa4f0b50afec9eae6d5b603cc4c3e8a408ed6b2bfaf28
User & Date: drh 2017-07-21 14:49:58
Context
2017-07-21
20:29
Fix typo in comment. No changes to code. check-in: 65ec077b user: mistachkin tags: batch-atomic-write
14:49
Additional documentation on the new VFS interface. No changes to code. check-in: 83077ec8 user: drh tags: batch-atomic-write
2017-07-20
21:18
Add the documentation text for the new VFS interfaces used by batch-atomic writes. check-in: 5e944eea user: drh tags: batch-atomic-write
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

   578    578   ** guaranteed to be unchanged.  The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
   579    579   ** flag indicates that a file cannot be deleted when open.  The
   580    580   ** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
   581    581   ** read-only media and cannot be changed even by processes with
   582    582   ** elevated privileges.
   583    583   **
   584    584   ** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
   585         -** filesystem can multiple write operations atomically when those
   586         -** write operations are bracketed by [SQLITE_IOCAP_BEGIN_ATOMIC_WRITE] and
   587         -** [SQLITE_IOCAP_ATOMIC_WRITE_COMMIT].
          585  +** filesystem supports doing multiple write operations atomically when those
          586  +** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
          587  +** [SQLITE_FCNTL_ATOMIC_WRITE_COMMIT].
   588    588   */
   589    589   #define SQLITE_IOCAP_ATOMIC                 0x00000001
   590    590   #define SQLITE_IOCAP_ATOMIC512              0x00000002
   591    591   #define SQLITE_IOCAP_ATOMIC1K               0x00000004
   592    592   #define SQLITE_IOCAP_ATOMIC2K               0x00000008
   593    593   #define SQLITE_IOCAP_ATOMIC4K               0x00000010
   594    594   #define SQLITE_IOCAP_ATOMIC8K               0x00000020
................................................................................
  1017   1017   **
  1018   1018   ** <li>[[SQLITE_FCNTL_RBU]]
  1019   1019   ** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
  1020   1020   ** the RBU extension only.  All other VFS should return SQLITE_NOTFOUND for
  1021   1021   ** this opcode.  
  1022   1022   **
  1023   1023   ** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
  1024         -** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, that
         1024  +** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
         1025  +** the file descriptor is placed in "batch write mode", which
  1025   1026   ** means all subsequent write operations will be deferred and done
  1026   1027   ** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].  Systems
  1027   1028   ** that do not support batch atomic writes will return SQLITE_NOTFOUND.
         1029  +** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
         1030  +** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
         1031  +** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
         1032  +** no VFS interface calls on the same [sqlite3_file] file descriptor
         1033  +** except for calls to the xWrite method and the xFileControl method
         1034  +** with [SQLITE_FCNTL_SIZE_HINT].
  1028   1035   **
  1029   1036   ** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
  1030         -** If the [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
         1037  +** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
  1031   1038   ** operations since the previous successful call to 
  1032   1039   ** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
  1033   1040   ** This file control returns [SQLITE_OK] if and only if the writes were
  1034   1041   ** all performed successfully and have been committed to persistent storage.
         1042  +** ^Regardless of whether or not it is successful, this file control takes
         1043  +** the file descriptor out of batch write mode so that all subsequent
         1044  +** write operations are independent.
         1045  +** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
         1046  +** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
  1035   1047   **
  1036   1048   ** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
  1037         -** If the [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
         1049  +** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
  1038   1050   ** operations since the previous successful call to 
  1039         -** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rollback.
         1051  +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
         1052  +** ^This file control takes the file descriptor out of batch write mode
         1053  +** so that all subsequent write operations are independent.
         1054  +** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
         1055  +** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
  1040   1056   ** </ul>
  1041   1057   */
  1042   1058   #define SQLITE_FCNTL_LOCKSTATE               1
  1043   1059   #define SQLITE_FCNTL_GET_LOCKPROXYFILE       2
  1044   1060   #define SQLITE_FCNTL_SET_LOCKPROXYFILE       3
  1045   1061   #define SQLITE_FCNTL_LAST_ERRNO              4
  1046   1062   #define SQLITE_FCNTL_SIZE_HINT               5