.Dd January 24, 2024
.Dt SQLITE3_TRACE 3
.Os
.Sh NAME
.Nm sqlite3_trace ,
.Nm sqlite3_profile
.Nd tracing and profiling functions
.Sh SYNOPSIS
.In sqlite3.h
.Ft void *
.Fo sqlite3_trace
.Fa "sqlite3*"
.Fa "void(*xTrace)(void*,const char*)"
.Fa "void*"
.Fc
.Ft void *
.Fo sqlite3_profile
.Fa "sqlite3*"
.Fa "void(*xProfile)(void*,const char*,sqlite3_uint64)"
.Fa "void*"
.Fc
.Sh DESCRIPTION
These routines are deprecated.
Use the
.Fn sqlite3_trace_v2
interface instead of the routines described here.
.Pp
These routines register callback functions that can be used for tracing
and profiling the execution of SQL statements.
.Pp
The callback function registered by sqlite3_trace() is invoked at various
times when an SQL statement is being run by
.Fn sqlite3_step .
The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
SQL statement text as the statement first begins executing.
Additional sqlite3_trace() callbacks might occur as each triggered
subprogram is entered.
The callbacks for triggers contain a UTF-8 SQL comment that identifies
the trigger.
.Pp
The SQLITE_TRACE_SIZE_LIMIT compile-time option
can be used to limit the length of bound parameter expansion
in the output of sqlite3_trace().
.Pp
The callback function registered by sqlite3_profile() is invoked as
each SQL statement finishes.
The profile callback contains the original statement text and an estimate
of wall-clock time of how long that statement took to run.
The profile callback time is in units of nanoseconds, however the current
implementation is only capable of millisecond resolution so the six
least significant digits in the time are meaningless.
Future versions of SQLite might provide greater resolution on the profiler
callback.
Invoking either
.Fn sqlite3_trace
or
.Fn sqlite3_trace_v2
will cancel the profile callback.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 3289.
.Bd -literal
SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
   void(*xTrace)(void*,const char*), void*);
SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
   void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
.Ed
.Sh SEE ALSO
.Xr sqlite3_step 3 ,
.Xr sqlite3_trace_v2 3