70 lines
2.8 KiB
Groff
70 lines
2.8 KiB
Groff
.Dd March 11, 2017
|
|
.Dt SQLITE3_TEMP_DIRECTORY 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_temp_directory
|
|
.Nd Name Of The Folder Holding Temporary Files
|
|
.Sh SYNOPSIS
|
|
.Vt char *sqlite3_temp_directory;
|
|
.Sh DESCRIPTION
|
|
If this global variable is made to point to a string which is the name
|
|
of a folder (a.k.a.
|
|
directory), then all temporary files created by SQLite when using a
|
|
built-in VFS will be placed in that directory.
|
|
If this variable is a NULL pointer, then SQLite performs a search for
|
|
an appropriate temporary file directory.
|
|
.Pp
|
|
Applications are strongly discouraged from using this global variable.
|
|
It is required to set a temporary folder on Windows Runtime (WinRT).
|
|
But for all other platforms, it is highly recommended that applications
|
|
neither read nor write this variable.
|
|
This global variable is a relic that exists for backwards compatibility
|
|
of legacy applications and should be avoided in new projects.
|
|
.Pp
|
|
It is not safe to read or modify this variable in more than one thread
|
|
at a time.
|
|
It is not safe to read or modify this variable if a database connection
|
|
is being used at the same time in a separate thread.
|
|
It is intended that this variable be set once as part of process initialization
|
|
and before any SQLite interface routines have been called and that
|
|
this variable remain unchanged thereafter.
|
|
.Pp
|
|
The temp_store_directory pragma may modify
|
|
this variable and cause it to point to memory obtained from sqlite3_malloc.
|
|
Furthermore, the temp_store_directory pragma
|
|
always assumes that any string that this variable points to is held
|
|
in memory obtained from sqlite3_malloc and the pragma
|
|
may attempt to free that memory using sqlite3_free.
|
|
Hence, if this variable is modified directly, either it should be made
|
|
NULL or made to point to memory obtained from sqlite3_malloc
|
|
or else the use of the temp_store_directory pragma
|
|
should be avoided.
|
|
Except when requested by the temp_store_directory pragma,
|
|
SQLite does not free the memory that sqlite3_temp_directory points
|
|
to.
|
|
If the application wants that memory to be freed, it must do so itself,
|
|
taking care to only do so after all database connection
|
|
objects have been destroyed.
|
|
.Pp
|
|
\fBNote to Windows Runtime users:\fP The temporary directory must be set
|
|
prior to calling sqlite3_open or sqlite3_open_v2.
|
|
Otherwise, various features that require the use of temporary files
|
|
may fail.
|
|
Here is an example of how to do this using C++ with the Windows Runtime:
|
|
.Bd -ragged
|
|
.Bd -literal
|
|
LPCWSTR zPath = Windows::Storage::ApplicationData::Current->
|
|
TemporaryFolder->Path->Data(); char zPathBuf[MAX_PATH + 1]; memset(zPathBuf,
|
|
0, sizeof(zPathBuf)); WideCharToMultiByte(CP_UTF8, 0, zPath, -1, zPathBuf,
|
|
sizeof(zPathBuf), NULL, NULL); sqlite3_temp_directory = sqlite3_mprintf("%s",
|
|
zPathBuf);
|
|
.Ed
|
|
.Pp
|
|
.Ed
|
|
.Pp
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3 3 ,
|
|
.Xr sqlite3_malloc 3 ,
|
|
.Xr sqlite3_open 3 ,
|
|
.Xr sqlite3_vfs 3
|