1.Dd $Mdocdate$ 2.Dt SQLITE3_WAL_CHECKPOINT_V2 3 3.Os 4.Sh NAME 5.Nm sqlite3_wal_checkpoint_v2 6.Nd Checkpoint a database 7.Sh SYNOPSIS 8.Ft int 9.Fo sqlite3_wal_checkpoint_v2 10.Fa "sqlite3 *db" 11.Fa "const char *zDb" 12.Fa "int eMode" 13.Fa "int *pnLog" 14.Fa "int *pnCkpt " 15.Fc 16.Sh DESCRIPTION 17Run a checkpoint operation on WAL database zDb attached to database 18handle db. 19The specific operation is determined by the value of the eMode parameter: 20.Bl -tag -width Ds 21.It SQLITE_CHECKPOINT_PASSIVECheckpoint as many frames as possible without 22waiting for any database readers or writers to finish. 23Sync the db file if all frames in the log are checkpointed. 24This mode is the same as calling sqlite3_wal_checkpoint(). 25The busy-handler callback is never invoked. 26.It SQLITE_CHECKPOINT_FULLThis mode blocks (calls the busy-handler callback) 27until there is no database writer and all readers are reading from 28the most recent database snapshot. 29It then checkpoints all frames in the log file and syncs the database 30file. 31This call blocks database writers while it is running, but not database 32readers. 33.It SQLITE_CHECKPOINT_RESTARTThis mode works the same way as SQLITE_CHECKPOINT_FULL, 34except after checkpointing the log file it blocks (calls the busy-handler 35callback) until all readers are reading from the database file only. 36This ensures that the next client to write to the database file restarts 37the log file from the beginning. 38This call blocks database writers while it is running, but not database 39readers. 40.El 41.Pp 42If pnLog is not NULL, then *pnLog is set to the total number of frames 43in the log file before returning. 44If pnCkpt is not NULL, then *pnCkpt is set to the total number of checkpointed 45frames (including any that were already checkpointed when this function 46is called). 47*pnLog and *pnCkpt may be populated even if sqlite3_wal_checkpoint_v2() 48returns other than SQLITE_OK. 49If no values are available because of an error, they are both set to 50-1 before returning to communicate this to the caller. 51.Pp 52All calls obtain an exclusive "checkpoint" lock on the database file. 53If any other process is running a checkpoint operation at the same 54time, the lock cannot be obtained and SQLITE_BUSY is returned. 55Even if there is a busy-handler configured, it will not be invoked 56in this case. 57.Pp 58The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive 59"writer" lock on the database file. 60If the writer lock cannot be obtained immediately, and a busy-handler 61is configured, it is invoked and the writer lock retried until either 62the busy-handler returns 0 or the lock is successfully obtained. 63The busy-handler is also invoked while waiting for database readers 64as described above. 65If the busy-handler returns 0 before the writer lock is obtained or 66while waiting for database readers, the checkpoint operation proceeds 67from that point in the same way as SQLITE_CHECKPOINT_PASSIVE - checkpointing 68as many frames as possible without blocking any further. 69SQLITE_BUSY is returned in this case. 70.Pp 71If parameter zDb is NULL or points to a zero length string, then the 72specified operation is attempted on all WAL databases. 73In this case the values written to output parameters *pnLog and *pnCkpt 74are undefined. 75If an SQLITE_BUSY error is encountered when processing one or more 76of the attached WAL databases, the operation is still attempted on 77any remaining attached databases and SQLITE_BUSY is returned to the 78caller. 79If any other error occurs while processing an attached database, processing 80is abandoned and the error code returned to the caller immediately. 81If no error (SQLITE_BUSY or otherwise) is encountered while processing 82the attached databases, SQLITE_OK is returned. 83.Pp 84If database zDb is the name of an attached database that is not in 85WAL mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to 86-1. 87If zDb is not NULL (or a zero length string) and is not the name of 88any attached database, SQLITE_ERROR is returned to the caller. 89