Version 3.1.1
WT_FILE_HANDLE Struct Reference

A file handle implementation returned by WT_FILE_SYSTEM::open_file. More...

Public Attributes

WT_FILE_SYSTEMfile_system
 The enclosing file system, set by WT_FILE_SYSTEM::open_file.
 
char * name
 The name of the file, set by WT_FILE_SYSTEM::open_file.
 
int(* close )(WT_FILE_HANDLE *file_handle, WT_SESSION *session)
 Close a file handle, the handle will not be further accessed by WiredTiger. More...
 
int(* fh_advise )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, wt_off_t len, int advice)
 Indicate expected future use of file ranges, based on the POSIX 1003.1 standard fadvise. More...
 
int(* fh_extend )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)
 Extend the file. More...
 
int(* fh_extend_nolock )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)
 Extend the file. More...
 
int(* fh_lock )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, bool lock)
 Lock/unlock a file from the perspective of other processes running in the system, where necessary. More...
 
int(* fh_map )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *mapped_regionp, size_t *lengthp, void *mapped_cookiep)
 Map a file into memory, based on the POSIX 1003.1 standard mmap. More...
 
int(* fh_map_discard )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *map, size_t length, void *mapped_cookie)
 Unmap part of a memory mapped file, based on the POSIX 1003.1 standard madvise. More...
 
int(* fh_map_preload )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, const void *map, size_t length, void *mapped_cookie)
 Preload part of a memory mapped file, based on the POSIX 1003.1 standard madvise. More...
 
int(* fh_unmap )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *mapped_region, size_t length, void *mapped_cookie)
 Unmap a memory mapped file, based on the POSIX 1003.1 standard munmap. More...
 
int(* fh_read )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, size_t len, void *buf)
 Read from a file, based on the POSIX 1003.1 standard pread. More...
 
int(* fh_size )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t *sizep)
 Return the size of a file. More...
 
int(* fh_sync )(WT_FILE_HANDLE *file_handle, WT_SESSION *session)
 Make outstanding file writes durable and do not return until writes are complete. More...
 
int(* fh_sync_nowait )(WT_FILE_HANDLE *file_handle, WT_SESSION *session)
 Schedule the outstanding file writes required for durability and return immediately. More...
 
int(* fh_truncate )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)
 Truncate the file. More...
 
int(* fh_write )(WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, size_t length, const void *buf)
 Write to a file, based on the POSIX 1003.1 standard pwrite. More...
 

Detailed Description

A file handle implementation returned by WT_FILE_SYSTEM::open_file.

Thread safety: Unless explicitly stated otherwise, WiredTiger may invoke methods on the WT_FILE_HANDLE interface from multiple threads concurrently. It is the responsibility of the implementation to protect any shared data.

See Custom File Systems for more information.

Examples:
ex_file_system.c.

Member Data Documentation

◆ close

int(* WT_FILE_HANDLE::close) (WT_FILE_HANDLE *file_handle, WT_SESSION *session)

Close a file handle, the handle will not be further accessed by WiredTiger.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
Examples:
ex_file_system.c.

◆ fh_advise

int(* WT_FILE_HANDLE::fh_advise) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, wt_off_t len, int advice)

Indicate expected future use of file ranges, based on the POSIX 1003.1 standard fadvise.

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

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
offsetthe file offset
lenthe size of the advisory
adviceone of WT_FILE_HANDLE_WILLNEED or WT_FILE_HANDLE_DONTNEED.
Examples:
ex_file_system.c.

◆ fh_extend

int(* WT_FILE_HANDLE::fh_extend) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)

Extend the file.

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

Any allocated disk space must read as 0 bytes, and no existing file data may change. Allocating all necessary underlying storage (not changing just the file's metadata), is likely to result in increased performance.

This method is not called by multiple threads concurrently (on the same file handle). If the file handle's extension method supports concurrent calls, set the WT_FILE_HANDLE::fh_extend_nolock method instead. See Custom File Systems for more information.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
offsetdesired file size after extension
Examples:
ex_file_system.c.

◆ fh_extend_nolock

int(* WT_FILE_HANDLE::fh_extend_nolock) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)

Extend the file.

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

Any allocated disk space must read as 0 bytes, and no existing file data may change. Allocating all necessary underlying storage (not only changing the file's metadata), is likely to result in increased performance.

This method may be called by multiple threads concurrently (on the same file handle). If the file handle's extension method does not support concurrent calls, set the WT_FILE_HANDLE::fh_extend method instead. See Custom File Systems for more information.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
offsetdesired file size after extension
Examples:
ex_file_system.c.

◆ fh_lock

int(* WT_FILE_HANDLE::fh_lock) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, bool lock)

Lock/unlock a file from the perspective of other processes running in the system, where necessary.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
lockwhether to lock or unlock
Examples:
ex_file_system.c.

◆ fh_map

int(* WT_FILE_HANDLE::fh_map) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *mapped_regionp, size_t *lengthp, void *mapped_cookiep)

Map a file into memory, based on the POSIX 1003.1 standard mmap.

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

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
[out]mapped_regionpa reference to a memory location into which should be stored a pointer to the start of the mapped region
[out]lengthpa reference to a memory location into which should be stored the length of the region
[out]mapped_cookiepa reference to a memory location into which can be optionally stored a pointer to an opaque cookie which is subsequently passed to WT_FILE_HANDLE::unmap.
Examples:
ex_file_system.c.

◆ fh_map_discard

int(* WT_FILE_HANDLE::fh_map_discard) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *map, size_t length, void *mapped_cookie)

Unmap part of a memory mapped file, based on the POSIX 1003.1 standard madvise.

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

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
mapa location in the mapped region unlikely to be used in the near future
lengththe length of the mapped region to discard
mapped_cookieany cookie set by the WT_FILE_HANDLE::map method
Examples:
ex_file_system.c.

◆ fh_map_preload

int(* WT_FILE_HANDLE::fh_map_preload) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, const void *map, size_t length, void *mapped_cookie)

Preload part of a memory mapped file, based on the POSIX 1003.1 standard madvise.

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

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
mapa location in the mapped region likely to be used in the near future
lengththe size of the mapped region to preload
mapped_cookieany cookie set by the WT_FILE_HANDLE::map method
Examples:
ex_file_system.c.

◆ fh_read

int(* WT_FILE_HANDLE::fh_read) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, size_t len, void *buf)

Read from a file, based on the POSIX 1003.1 standard pread.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
offsetthe offset in the file to start reading from
lenthe amount to read
[out]bufbuffer to hold the content read from file
Examples:
ex_file_system.c.

◆ fh_size

int(* WT_FILE_HANDLE::fh_size) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t *sizep)

Return the size of a file.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
sizepthe size of the file
Examples:
ex_file_system.c.

◆ fh_sync

int(* WT_FILE_HANDLE::fh_sync) (WT_FILE_HANDLE *file_handle, WT_SESSION *session)

Make outstanding file writes durable and do not return until writes are complete.

This method is not required for read-only files, and should be set to NULL when not supported by the file.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
Examples:
ex_file_system.c.

◆ fh_sync_nowait

int(* WT_FILE_HANDLE::fh_sync_nowait) (WT_FILE_HANDLE *file_handle, WT_SESSION *session)

Schedule the outstanding file writes required for durability and return immediately.

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

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
Examples:
ex_file_system.c.

◆ fh_truncate

int(* WT_FILE_HANDLE::fh_truncate) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset)

Truncate the file.

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

This method is not called by multiple threads concurrently (on the same file handle).

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
offsetdesired file size after truncate
Examples:
ex_file_system.c.

◆ fh_unmap

int(* WT_FILE_HANDLE::fh_unmap) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, void *mapped_region, size_t length, void *mapped_cookie)

Unmap a memory mapped file, based on the POSIX 1003.1 standard munmap.

This method is only required if a valid implementation of map is provided by the file, and should be set to NULL otherwise.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
mapped_regiona pointer to the start of the mapped region
lengththe length of the mapped region
mapped_cookieany cookie set by the WT_FILE_HANDLE::map method
Examples:
ex_file_system.c.

◆ fh_write

int(* WT_FILE_HANDLE::fh_write) (WT_FILE_HANDLE *file_handle, WT_SESSION *session, wt_off_t offset, size_t length, const void *buf)

Write to a file, based on the POSIX 1003.1 standard pwrite.

This method is not required for read-only files, and should be set to NULL when not supported by the file.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Parameters
file_handlethe WT_FILE_HANDLE
sessionthe current WiredTiger session
offsetoffset at which to start writing
lengthamount of data to write
bufcontent to be written to the file
Examples:
ex_file_system.c.