.Dd January 24, 2024
.Dt SQLITE3_CREATE_FILENAME 3
.Os
.Sh NAME
.Nm sqlite3_create_filename ,
.Nm sqlite3_free_filename
.Nd create and destroy VFS filenames
.Sh SYNOPSIS
.In sqlite3.h
.Ft sqlite3_filename
.Fo sqlite3_create_filename
.Fa "const char *zDatabase"
.Fa "const char *zJournal"
.Fa "const char *zWal"
.Fa "int nParam"
.Fa "const char **azParam"
.Fc
.Ft void
.Fo sqlite3_free_filename
.Fa "sqlite3_filename"
.Fc
.Sh DESCRIPTION
These interfaces are provided for use by VFS shim implementations
and are not useful outside of that context.
.Pp
The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version
of database filename D with corresponding journal file J and WAL file
W and with N URI parameters key/values pairs in the array P.
The result from sqlite3_create_filename(D,J,W,N,P) is a pointer to
a database filename that is safe to pass to routines like:
.Bl -bullet
.It
.Fn sqlite3_uri_parameter ,
.It
.Fn sqlite3_uri_boolean ,
.It
.Fn sqlite3_uri_int64 ,
.It
.Fn sqlite3_uri_key ,
.It
.Fn sqlite3_filename_database ,
.It
.Fn sqlite3_filename_journal ,
or
.It
.Fn sqlite3_filename_wal .
.El
.Pp
If a memory allocation error occurs, sqlite3_create_filename() might
return a NULL pointer.
The memory obtained from sqlite3_create_filename(X) must be released
by a corresponding call to sqlite3_free_filename(Y).
.Pp
The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an
array of 2*N pointers to strings.
Each pair of pointers in this array corresponds to a key and value
for a query parameter.
The P parameter may be a NULL pointer if N is zero.
None of the 2*N pointers in the P array may be NULL pointers and key
pointers should not be empty strings.
None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P)
may be NULL pointers, though they can be empty strings.
.Pp
The sqlite3_free_filename(Y) routine releases a memory allocation previously
obtained from sqlite3_create_filename().
Invoking sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless
no-op.
.Pp
If the Y parameter to sqlite3_free_filename(Y) is anything other than
a NULL pointer or a pointer previously acquired from sqlite3_create_filename(),
then bad things such as heap corruption or segfaults may occur.
The value Y should not be used again after sqlite3_free_filename(Y)
has been called.
This means that if the
.Fn sqlite3_vfs.xOpen
method of a VFS has been called using Y, then the correspondingsqlite3_module.xClose()
method should also be invoked prior to calling sqlite3_free_filename(Y).
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 3876.
.Bd -literal
SQLITE_API sqlite3_filename sqlite3_create_filename(
  const char *zDatabase,
  const char *zJournal,
  const char *zWal,
  int nParam,
  const char **azParam
);
SQLITE_API void sqlite3_free_filename(sqlite3_filename);
.Ed
.Sh SEE ALSO
.Xr sqlite3_filename_database 3 ,
.Xr sqlite3_uri_parameter 3