1.Dd January 24, 2024 2.Dt SQLITE3_AUTOVACUUM_PAGES 3 3.Os 4.Sh NAME 5.Nm sqlite3_autovacuum_pages 6.Nd autovacuum compaction amount callback 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3_autovacuum_pages 11.Fa "sqlite3 *db" 12.Fa "unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int)" 13.Fa "void*" 14.Fa "void(*)(void*)" 15.Fc 16.Sh DESCRIPTION 17The sqlite3_autovacuum_pages(D,C,P,X) interface registers a callback 18function C that is invoked prior to each autovacuum of the database 19file. 20The callback is passed a copy of the generic data pointer (P), the 21schema-name of the attached database that is being autovacuumed, the 22size of the database file in pages, the number of free pages, and the 23number of bytes per page, respectively. 24The callback should return the number of free pages that should be 25removed by the autovacuum. 26If the callback returns zero, then no autovacuum happens. 27If the value returned is greater than or equal to the number of free 28pages, then a complete autovacuum happens. 29.Pp 30If there are multiple ATTACH-ed database files that are being modified 31as part of a transaction commit, then the autovacuum pages callback 32is invoked separately for each file. 33.Pp 34\fBThe callback is not reentrant.\fP The callback function should not attempt 35to invoke any other SQLite interface. 36If it does, bad things may happen, including segmentation faults and 37corrupt database files. 38The callback function should be a simple function that does some arithmetic 39on its input parameters and returns a result. 40.Pp 41The X parameter to sqlite3_autovacuum_pages(D,C,P,X) is an optional 42destructor for the P parameter. 43If X is not NULL, then X(P) is invoked whenever the database connection 44closes or when the callback is overwritten by another invocation of 45sqlite3_autovacuum_pages(). 46.Pp 47There is only one autovacuum pages callback per database connection. 48Each call to the sqlite3_autovacuum_pages() interface overrides all 49previous invocations for that database connection. 50If the callback argument (C) to sqlite3_autovacuum_pages(D,C,P,X) is 51a NULL pointer, then the autovacuum steps callback is canceled. 52The return value from sqlite3_autovacuum_pages() is normally SQLITE_OK, 53but might be some other error code if something goes wrong. 54The current implementation will only return SQLITE_OK or SQLITE_MISUSE, 55but other return codes might be added in future releases. 56.Pp 57If no autovacuum pages callback is specified (the usual case) or a 58NULL pointer is provided for the callback, then the default behavior 59is to vacuum all free pages. 60So, in other words, the default behavior is the same as if the callback 61function were something like this: 62.Bd -ragged 63.Bd -literal 64 unsigned int demonstration_autovac_pages_callback( void *pClientData, 65 const char *zSchema, unsigned int nDbPage, unsigned 66int nFreePage, unsigned int nBytePerPage ){ return 67nFreePage; } 68.Ed 69.Pp 70.Ed 71.Pp 72.Sh IMPLEMENTATION NOTES 73These declarations were extracted from the 74interface documentation at line 6772. 75.Bd -literal 76SQLITE_API int sqlite3_autovacuum_pages( 77 sqlite3 *db, 78 unsigned int(*)(void*,const char*,unsigned int,unsigned int,unsigned int), 79 void*, 80 void(*)(void*) 81); 82.Ed 83