Version 11.1.0
WT_FILE_SYSTEM Struct Reference

The interface implemented by applications to provide a custom file system implementation. More...

Public Attributes

int(* fs_directory_list )(WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *directory, const char *prefix, char ***dirlist, uint32_t *countp)
 Return a list of file names for the named directory. More...
 
int(* fs_directory_list_free )(WT_FILE_SYSTEM *file_system, WT_SESSION *session, char **dirlist, uint32_t count)
 Free memory allocated by WT_FILE_SYSTEM::directory_list. More...
 
int(* fs_exist )(WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name, bool *existp)
 Return if the named file system object exists. More...
 
int(* fs_open_file )(WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name, WT_FS_OPEN_FILE_TYPE file_type, uint32_t flags, WT_FILE_HANDLE **file_handlep)
 Open a handle for a named file system object. More...
 
int(* fs_remove )(WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name, uint32_t flags)
 Remove a named file system object. More...
 
int(* fs_rename )(WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *from, const char *to, uint32_t flags)
 Rename a named file system object. More...
 
int(* fs_size )(WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name, wt_off_t *sizep)
 Return the size of a named file system object. More...
 
int(* terminate )(WT_FILE_SYSTEM *file_system, WT_SESSION *session)
 A callback performed when the file system is closed and will no longer be accessed by the WiredTiger database. More...
 

Detailed Description

The interface implemented by applications to provide a custom file system implementation.

Thread safety: WiredTiger may invoke methods on the WT_FILE_SYSTEM interface from multiple threads concurrently. It is the responsibility of the implementation to protect any shared data.

Applications register implementations with WiredTiger by calling WT_CONNECTION::set_file_system. See Custom File Systems for more information.

/*
* Setup a configuration string that will load our custom file system. Use the special local
* extension to indicate that the entry point is in the same executable. Also enable early load
* for this extension, since WiredTiger needs to be able to find it before doing any file
* operations. Finally, pass in two pieces of configuration information to our initialization
* function as the "config" value.
*/
open_config =
"create,log=(enabled=true),extensions=(local={entry=demo_file_system_create,early_load=true,"
"config={config_string=\"demo-file-system\",config_value=37}})";
/* Open a connection to the database, creating it if necessary. */
if ((ret = wiredtiger_open(home, NULL, open_config, &conn)) != 0) {
fprintf(stderr, "Error connecting to %s: %s\n", home == NULL ? "." : home,
return (EXIT_FAILURE);
}
Examples
ex_file_system.c.

Member Data Documentation

◆ fs_directory_list

int(* WT_FILE_SYSTEM::fs_directory_list) (WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *directory, const char *prefix, char ***dirlist, uint32_t *countp)

Return a list of file names for the named directory.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_systemthe WT_FILE_SYSTEM
sessionthe current WiredTiger session
directorythe name of the directory
prefixif not NULL, only files with names matching the prefix are returned
[out]dirlistthe method returns an allocated array of individually allocated strings, one for each entry in the directory.
[out]countpthe number of entries returned
Examples
ex_file_system.c.

◆ fs_directory_list_free

int(* WT_FILE_SYSTEM::fs_directory_list_free) (WT_FILE_SYSTEM *file_system, WT_SESSION *session, char **dirlist, uint32_t count)

Free memory allocated by WT_FILE_SYSTEM::directory_list.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_systemthe WT_FILE_SYSTEM
sessionthe current WiredTiger session
dirlistarray returned by WT_FILE_SYSTEM::directory_list
countcount returned by WT_FILE_SYSTEM::directory_list
Examples
ex_file_system.c.

◆ fs_exist

int(* WT_FILE_SYSTEM::fs_exist) (WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name, bool *existp)

Return if the named file system object exists.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_systemthe WT_FILE_SYSTEM
sessionthe current WiredTiger session
namethe name of the file
[out]existpIf the named file system object exists
Examples
ex_file_system.c.

◆ fs_open_file

int(* WT_FILE_SYSTEM::fs_open_file) (WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name, WT_FS_OPEN_FILE_TYPE file_type, uint32_t flags, WT_FILE_HANDLE **file_handlep)

Open a handle for a named file system object.

The method should return ENOENT if the file is not being created and does not exist.

The method should return EACCES if the file cannot be opened in the requested mode (for example, a file opened for writing in a readonly file system).

The method should return EBUSY if WT_FS_OPEN_EXCLUSIVE is set and the file is in use.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_systemthe WT_FILE_SYSTEM
sessionthe current WiredTiger session
namethe name of the file system object
file_typethe type of the file The file type is provided to allow optimization for different file access patterns.
flagsflags indicating how to open the file, one or more of WT_FS_OPEN_CREATE, WT_FS_OPEN_DIRECTIO, WT_FS_OPEN_DURABLE, WT_FS_OPEN_EXCLUSIVE or WT_FS_OPEN_READONLY.
[out]file_handlepthe handle to the newly opened file. File system implementations must allocate memory for the handle and the WT_FILE_HANDLE::name field, and fill in the WT_FILE_HANDLE:: fields. Applications wanting to associate private information with the WT_FILE_HANDLE:: structure should declare and allocate their own structure as a superset of a WT_FILE_HANDLE:: structure.
Examples
ex_file_system.c.

◆ fs_remove

int(* WT_FILE_SYSTEM::fs_remove) (WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name, uint32_t flags)

Remove a named file system object.

This method is not required for readonly file systems and should be set to NULL when not required by the file system.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_systemthe WT_FILE_SYSTEM
sessionthe current WiredTiger session
namethe name of the file system object
flags0 or WT_FS_DURABLE
Examples
ex_file_system.c.

◆ fs_rename

int(* WT_FILE_SYSTEM::fs_rename) (WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *from, const char *to, uint32_t flags)

Rename a named file system object.

This method is not required for readonly file systems and should be set to NULL when not required by the file system.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_systemthe WT_FILE_SYSTEM
sessionthe current WiredTiger session
fromthe original name of the object
tothe new name for the object
flags0 or WT_FS_DURABLE
Examples
ex_file_system.c.

◆ fs_size

int(* WT_FILE_SYSTEM::fs_size) (WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name, wt_off_t *sizep)

Return the size of a named file system object.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_systemthe WT_FILE_SYSTEM
sessionthe current WiredTiger session
namethe name of the file system object
[out]sizepthe size of the file system entry
Examples
ex_file_system.c.

◆ terminate

int(* WT_FILE_SYSTEM::terminate) (WT_FILE_SYSTEM *file_system, WT_SESSION *session)

A callback performed when the file system is closed and will no longer be accessed by the WiredTiger database.

This method is not required and should be set to NULL when not required by the file system.

The WT_FILE_SYSTEM::terminate callback is intended to allow cleanup; the handle will not be subsequently accessed by WiredTiger.

Examples
ex_file_system.c.
wiredtiger_strerror
const char * wiredtiger_strerror(int error)
Return information about a WiredTiger error as a string (see WT_SESSION::strerror for a thread-safe A...
wiredtiger_open
int wiredtiger_open(const char *home, WT_EVENT_HANDLER *event_handler, const char *config, WT_CONNECTION **connectionp)
Open a connection to a database.