1.Dd January 24, 2024 2.Dt SQLITE3_CREATE_FILENAME 3 3.Os 4.Sh NAME 5.Nm sqlite3_create_filename , 6.Nm sqlite3_free_filename 7.Nd create and destroy VFS filenames 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft sqlite3_filename 11.Fo sqlite3_create_filename 12.Fa "const char *zDatabase" 13.Fa "const char *zJournal" 14.Fa "const char *zWal" 15.Fa "int nParam" 16.Fa "const char **azParam" 17.Fc 18.Ft void 19.Fo sqlite3_free_filename 20.Fa "sqlite3_filename" 21.Fc 22.Sh DESCRIPTION 23These interfaces are provided for use by VFS shim implementations 24and are not useful outside of that context. 25.Pp 26The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version 27of database filename D with corresponding journal file J and WAL file 28W and with N URI parameters key/values pairs in the array P. 29The result from sqlite3_create_filename(D,J,W,N,P) is a pointer to 30a database filename that is safe to pass to routines like: 31.Bl -bullet 32.It 33.Fn sqlite3_uri_parameter , 34.It 35.Fn sqlite3_uri_boolean , 36.It 37.Fn sqlite3_uri_int64 , 38.It 39.Fn sqlite3_uri_key , 40.It 41.Fn sqlite3_filename_database , 42.It 43.Fn sqlite3_filename_journal , 44or 45.It 46.Fn sqlite3_filename_wal . 47.El 48.Pp 49If a memory allocation error occurs, sqlite3_create_filename() might 50return a NULL pointer. 51The memory obtained from sqlite3_create_filename(X) must be released 52by a corresponding call to sqlite3_free_filename(Y). 53.Pp 54The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an 55array of 2*N pointers to strings. 56Each pair of pointers in this array corresponds to a key and value 57for a query parameter. 58The P parameter may be a NULL pointer if N is zero. 59None of the 2*N pointers in the P array may be NULL pointers and key 60pointers should not be empty strings. 61None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) 62may be NULL pointers, though they can be empty strings. 63.Pp 64The sqlite3_free_filename(Y) routine releases a memory allocation previously 65obtained from sqlite3_create_filename(). 66Invoking sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless 67no-op. 68.Pp 69If the Y parameter to sqlite3_free_filename(Y) is anything other than 70a NULL pointer or a pointer previously acquired from sqlite3_create_filename(), 71then bad things such as heap corruption or segfaults may occur. 72The value Y should not be used again after sqlite3_free_filename(Y) 73has been called. 74This means that if the 75.Fn sqlite3_vfs.xOpen 76method of a VFS has been called using Y, then the correspondingsqlite3_module.xClose() 77method should also be invoked prior to calling sqlite3_free_filename(Y). 78.Sh IMPLEMENTATION NOTES 79These declarations were extracted from the 80interface documentation at line 3876. 81.Bd -literal 82SQLITE_API sqlite3_filename sqlite3_create_filename( 83 const char *zDatabase, 84 const char *zJournal, 85 const char *zWal, 86 int nParam, 87 const char **azParam 88); 89SQLITE_API void sqlite3_free_filename(sqlite3_filename); 90.Ed 91.Sh SEE ALSO 92.Xr sqlite3_filename_database 3 , 93.Xr sqlite3_uri_parameter 3 94