1.Dd January 24, 2024 2.Dt SQLITE3_SNAPSHOT_GET 3 3.Os 4.Sh NAME 5.Nm sqlite3_snapshot_get 6.Nd record a database snapshot 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3_snapshot_get 11.Fa "sqlite3 *db" 12.Fa "const char *zSchema" 13.Fa "sqlite3_snapshot **ppSnapshot" 14.Fc 15.Sh DESCRIPTION 16The sqlite3_snapshot_get(D,S,P) interface 17attempts to make a new sqlite3_snapshot object that 18records the current state of schema S in database connection D. 19On success, the sqlite3_snapshot_get(D,S,P) 20interface writes a pointer to the newly created sqlite3_snapshot 21object into *P and returns SQLITE_OK. 22If there is not already a read-transaction open on schema S when this 23function is called, one is opened automatically. 24.Pp 25The following must be true for this function to succeed. 26If any of the following statements are false when sqlite3_snapshot_get() 27is called, SQLITE_ERROR is returned. 28The final value of *P is undefined in this case. 29.Bl -bullet 30.It 31The database handle must not be in autocommit mode. 32.It 33Schema S of database connection D must be a WAL mode 34database. 35.It 36There must not be a write transaction open on schema S of database 37connection D. 38.It 39One or more transactions must have been written to the current wal 40file since it was created on disk (by any connection). 41This means that a snapshot cannot be taken on a wal mode database with 42no wal file immediately after it is first opened. 43At least one transaction must be written to it first. 44.El 45.Pp 46This function may also return SQLITE_NOMEM. 47If it is called with the database handle in autocommit mode but fails 48for some other reason, whether or not a read transaction is opened 49on schema S is undefined. 50.Pp 51The sqlite3_snapshot object returned from a successful 52call to 53.Fn sqlite3_snapshot_get 54must be freed using 55.Fn sqlite3_snapshot_free 56to avoid a memory leak. 57.Pp 58The 59.Fn sqlite3_snapshot_get 60interface is only available when the SQLITE_ENABLE_SNAPSHOT 61compile-time option is used. 62.Sh IMPLEMENTATION NOTES 63These declarations were extracted from the 64interface documentation at line 10470. 65.Bd -literal 66SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_snapshot_get( 67 sqlite3 *db, 68 const char *zSchema, 69 sqlite3_snapshot **ppSnapshot 70); 71.Ed 72.Sh SEE ALSO 73.Xr sqlite3 3 , 74.Xr sqlite3_get_autocommit 3 , 75.Xr sqlite3_snapshot 3 , 76.Xr sqlite3_snapshot_free 3 77