1.Dd January 24, 2024 2.Dt SQLITE3_EXEC 3 3.Os 4.Sh NAME 5.Nm sqlite3_exec 6.Nd one-Step query execution interface 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3_exec 11.Fa "sqlite3*" 12.Fa "const char *sql" 13.Fa "int (*callback)(void*,int,char**,char**)" 14.Fa "void *" 15.Fa "char **errmsg" 16.Fc 17.Sh DESCRIPTION 18The sqlite3_exec() interface is a convenience wrapper around 19.Fn sqlite3_prepare_v2 , 20.Fn sqlite3_step , 21and 22.Fn sqlite3_finalize , 23that allows an application to run multiple statements of SQL without 24having to use a lot of C code. 25.Pp 26The sqlite3_exec() interface runs zero or more UTF-8 encoded, semicolon-separate 27SQL statements passed into its 2nd argument, in the context of the 28database connection passed in as its 1st argument. 29If the callback function of the 3rd argument to sqlite3_exec() is not 30NULL, then it is invoked for each result row coming out of the evaluated 31SQL statements. 32The 4th argument to sqlite3_exec() is relayed through to the 1st argument 33of each callback invocation. 34If the callback pointer to sqlite3_exec() is NULL, then no callback 35is ever invoked and result rows are ignored. 36.Pp 37If an error occurs while evaluating the SQL statements passed into 38sqlite3_exec(), then execution of the current statement stops and subsequent 39statements are skipped. 40If the 5th parameter to sqlite3_exec() is not NULL then any error message 41is written into memory obtained from 42.Fn sqlite3_malloc 43and passed back through the 5th parameter. 44To avoid memory leaks, the application should invoke 45.Fn sqlite3_free 46on error message strings returned through the 5th parameter of sqlite3_exec() 47after the error message string is no longer needed. 48If the 5th parameter to sqlite3_exec() is not NULL and no errors occur, 49then sqlite3_exec() sets the pointer in its 5th parameter to NULL before 50returning. 51.Pp 52If an sqlite3_exec() callback returns non-zero, the sqlite3_exec() 53routine returns SQLITE_ABORT without invoking the callback again and 54without running any subsequent SQL statements. 55.Pp 56The 2nd argument to the sqlite3_exec() callback function is the number 57of columns in the result. 58The 3rd argument to the sqlite3_exec() callback is an array of pointers 59to strings obtained as if from 60.Fn sqlite3_column_text , 61one for each column. 62If an element of a result row is NULL then the corresponding string 63pointer for the sqlite3_exec() callback is a NULL pointer. 64The 4th argument to the sqlite3_exec() callback is an array of pointers 65to strings where each entry represents the name of corresponding result 66column as obtained from 67.Fn sqlite3_column_name . 68If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer 69to an empty string, or a pointer that contains only whitespace and/or 70SQL comments, then no SQL statements are evaluated and the database 71is not changed. 72.Pp 73Restrictions: 74.Bl -bullet 75.It 76The application must ensure that the 1st parameter to sqlite3_exec() 77is a valid and open database connection. 78.It 79The application must not close the database connection 80specified by the 1st parameter to sqlite3_exec() while sqlite3_exec() 81is running. 82.It 83The application must not modify the SQL statement text passed into 84the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running. 85.El 86.Pp 87.Sh IMPLEMENTATION NOTES 88These declarations were extracted from the 89interface documentation at line 364. 90.Bd -literal 91SQLITE_API int sqlite3_exec( 92 sqlite3*, /* An open database */ 93 const char *sql, /* SQL to be evaluated */ 94 int (*callback)(void*,int,char**,char**), /* Callback function */ 95 void *, /* 1st argument to callback */ 96 char **errmsg /* Error msg written here */ 97); 98.Ed 99.Sh SEE ALSO 100.Xr sqlite3 3 , 101.Xr sqlite3_column_blob 3 , 102.Xr sqlite3_column_name 3 , 103.Xr sqlite3_finalize 3 , 104.Xr sqlite3_malloc 3 , 105.Xr sqlite3_prepare 3 , 106.Xr sqlite3_step 3 107