Home | History | Annotate | Line # | Download | only in man 
      1 .Dd April 29, 2026
      2 .Dt SQLITE3_DB_CACHEFLUSH 3
      3 .Os
      4 .Sh NAME
      5 .Nm sqlite3_db_cacheflush
      6 .Nd flush caches to disk mid-transaction
      7 .Sh SYNOPSIS
      8 .In sqlite3.h
      9 .Ft int
     10 .Fo sqlite3_db_cacheflush
     11 .Fa "sqlite3*"
     12 .Fc
     13 .Sh DESCRIPTION
     14 If a write-transaction is open on database connection
     15 D when the sqlite3_db_cacheflush(D) interface
     16 is invoked, any dirty pages in the pager-cache that are not currently
     17 in use are written out to disk.
     18 A dirty page may be in use if a database cursor created by an active
     19 SQL statement is reading from it, or if it is page 1 of a database
     20 file (page 1 is always "in use").
     21 The sqlite3_db_cacheflush(D) interface flushes
     22 caches for all schemas - "main", "temp", and any attached databases.
     23 .Pp
     24 If this function needs to obtain extra database locks before dirty
     25 pages can be flushed to disk, it does so.
     26 If those locks cannot be obtained immediately and there is a busy-handler
     27 callback configured, it is invoked in the usual manner.
     28 If the required lock still cannot be obtained, then the database is
     29 skipped and an attempt made to flush any dirty pages belonging to the
     30 next (if any) database.
     31 If any databases are skipped because locks cannot be obtained, but
     32 no other error occurs, this function returns SQLITE_BUSY.
     33 .Pp
     34 If any other error occurs while flushing dirty pages to disk (for example
     35 an IO error or out-of-memory condition), then processing is abandoned
     36 and an SQLite error code is returned to the caller immediately.
     37 .Pp
     38 Otherwise, if no error occurs,
     39 .Fn sqlite3_db_cacheflush
     40 returns SQLITE_OK.
     41 .Pp
     42 This function does not set the database handle error code or message
     43 returned by the
     44 .Fn sqlite3_errcode
     45 and
     46 .Fn sqlite3_errmsg
     47 functions.
     48 .Sh IMPLEMENTATION NOTES
     49 These declarations were extracted from the
     50 interface documentation at line 10769.
     51 .Bd -literal
     52 SQLITE_API int sqlite3_db_cacheflush(sqlite3*);
     53 .Ed
     54 .Sh SEE ALSO
     55 .Xr sqlite3 3 ,
     56 .Xr sqlite3_errcode 3
     57