Detailed Description

Seastar provides a file API to deal with persistent storage. Unlike most file APIs, seastar offers unbuffered file I/O (similar to, and based on, O_DIRECT). Unbuffered I/O means that the application is required to do its own caching, but delivers better performance if this caching is done correctly.

For random I/O or sequential unbuffered I/O, the file class provides a set of methods for reading, writing, discarding, or otherwise manipulating a file. For buffered sequential I/O, see make_file_input_stream() and make_file_output_stream().

Modules
	File and Stream Utilities
	These utilities are provided to help perform operations on files and I/O streams.

Classes
struct	seastar::directory_entry
	A directory entry being listed. More...

struct	seastar::stat_data
	Filesystem object stat information. More...

struct	seastar::file_open_options

class	seastar::file_handle_impl

class	seastar::file_impl

class	seastar::file

class	seastar::file_handle
	A shard-transportable handle to a file. More...

class	seastar::layered_file_impl

struct	seastar::follow_symlink_tag

Typedefs
using	seastar::follow_symlink = bool_class< follow_symlink_tag >

Enumerations
enum class	seastar::open_flags { rw = O_RDWR , ro = O_RDONLY , wo = O_WRONLY , create = O_CREAT , truncate = O_TRUNC , exclusive = O_EXCL , dsync = O_DSYNC }

enum class	seastar::directory_entry_type { unknown , block_device , char_device , directory , fifo , link , regular , socket }

enum class	seastar::fs_type { other , xfs , ext2 , ext3 , ext4 , btrfs , hfs , tmpfs }
	Enumeration describing the type of a particular filesystem.

enum class	access_flags { exists = F_OK , read = R_OK , write = W_OK , execute = X_OK , lookup = execute }

enum class	file_permissions { user_read = S_IRUSR , user_write = S_IWUSR , user_execute = S_IXUSR , group_read = S_IRGRP , group_write = S_IWGRP , group_execute = S_IXGRP , others_read = S_IROTH , others_write = S_IWOTH , others_execute = S_IXOTH , user_permissions = user_read \| user_write \| user_execute , group_permissions = group_read \| group_write \| group_execute , others_permissions = others_read \| others_write \| others_execute , all_permissions = user_permissions \| group_permissions \| others_permissions , default_file_permissions = user_read \| user_write \| group_read \| group_write \| others_read \| others_write , default_dir_permissions = all_permissions }

Functions
open_flags	seastar::operator\| (open_flags a, open_flags b)

void	seastar::operator\|= (open_flags &a, open_flags b)

open_flags	seastar::operator& (open_flags a, open_flags b)

void	seastar::operator&= (open_flags &a, open_flags b)

access_flags	seastar::operator\| (access_flags a, access_flags b)

access_flags	seastar::operator& (access_flags a, access_flags b)

constexpr file_permissions	seastar::operator\| (file_permissions a, file_permissions b)

constexpr file_permissions	seastar::operator& (file_permissions a, file_permissions b)

future< shared_ptr< file_impl > >	seastar::make_file_impl (int fd, file_open_options options, int oflags, struct stat st) noexcept

template<typename Func >
auto	seastar::with_file (future< file > file_fut, Func func) noexcept
	Helper for ensuring a file is closed after `func` is called. More...

template<typename Func >
auto	seastar::with_file_close_on_failure (future< file > file_fut, Func func) noexcept
	Helper for ensuring a file is closed if `func` fails. More...

future	seastar::check_direct_io_support (std::string_view path) noexcept

future	seastar::make_directory (std::string_view name, file_permissions permissions=file_permissions::default_dir_permissions) noexcept

future	seastar::touch_directory (std::string_view name, file_permissions permissions=file_permissions::default_dir_permissions) noexcept

future	seastar::recursive_touch_directory (std::string_view name, file_permissions permissions=file_permissions::default_dir_permissions) noexcept

future	seastar::sync_directory (std::string_view name) noexcept

future	seastar::remove_file (std::string_view name) noexcept

future	seastar::rename_file (std::string_view old_name, std::string_view new_name) noexcept

future< stat_data >	seastar::file_stat (std::string_view name, follow_symlink fs=follow_symlink::yes) noexcept

future< uint64_t >	seastar::file_size (std::string_view name) noexcept

future< bool >	seastar::file_accessible (std::string_view name, access_flags flags) noexcept

future< bool >	seastar::file_exists (std::string_view name) noexcept

future< std::optional< directory_entry_type > >	seastar::file_type (std::string_view name, follow_symlink follow=follow_symlink::yes) noexcept

future	seastar::link_file (std::string_view oldpath, std::string_view newpath) noexcept

future	seastar::chmod (std::string_view name, file_permissions permissions) noexcept

future< fs_type >	seastar::file_system_at (std::string_view name) noexcept

future< uint64_t >	seastar::fs_avail (std::string_view name) noexcept

future< uint64_t >	seastar::fs_free (std::string_view name) noexcept

future< file >	open_file_dma (std::string_view name, open_flags flags) noexcept

future< file >	open_file_dma (std::string_view name, open_flags flags, file_open_options options) noexcept

future< file >	open_directory (std::string_view name) noexcept

Class Documentation

◆ seastar::directory_entry

struct seastar::directory_entry

Class Members
sstring	name	Name of the file in a directory entry. Will never be "." or "..". Only the last component is included.
optional< directory_entry_type >	type	Type of the directory entry, if known.

◆ seastar::stat_data

struct seastar::stat_data

Class Members
uint64_t	allocated_size
uint64_t	block_size
uint64_t	device_id
uint64_t	gid
uint64_t	inode_number
uint64_t	mode
uint64_t	number_of_links
uint64_t	rdev
uint64_t	size
time_point	time_accessed
time_point	time_changed
time_point	time_modified
directory_entry_type	type
uint64_t	uid

◆ seastar::follow_symlink_tag

struct seastar::follow_symlink_tag

Enumeration Type Documentation

◆ directory_entry_type

enum seastar::directory_entry_type

strong

Enumeration describing the type of a directory entry being listed.

See also: file::list_directory()

◆ open_flags

enum seastar::open_flags

strong

Enumeration describing how a file is to be opened.

See also: file::open_file_dma()

Function Documentation

◆ check_direct_io_support()

future seastar::check_direct_io_support ( std::string_view path )

noexcept

Checks if a given directory supports direct io

Seastar bypasses the Operating System caches and issues direct io to the underlying block devices. Projects using seastar should check if the directory lies in a filesystem that support such operations. This function can be used to do that.

It will return if direct io can be used, or throw an std::system_error exception, with the EINVAL error code.

A std::system_error with the respective error code is also thrown if path is not a directory.

Parameters

path	the directory we need to verify.

◆ chmod()

future seastar::chmod	(	std::string_view	name,
		file_permissions	permissions
	)

noexcept

Changes the permissions mode of a file or directory

Parameters

name	name of the file ot directory to change
permissions	permissions to set

◆ file_accessible()

future<bool> seastar::file_accessible	(	std::string_view	name,
		access_flags	flags
	)

noexcept

Check file access.

Parameters

name	name of the file to check
flags	bit pattern containing type of access to check (read/write/execute or exists).

If only access_flags::exists is queried, returns true if the file exists, or false otherwise. Throws a std::filesystem::filesystem_error exception if any error other than ENOENT is encountered.

If any of the access_flags (read/write/execute) is set, returns true if the file exists and is accessible with the requested flags, or false if the file exists and is not accessible as queried. Throws a std::filesystem::filesystem_error exception if any error other than EACCES is encountered. Note that if any path component leading to the file is not searchable, the file is considered inaccessible with the requested mode and false will be returned.

◆ file_exists()

future<bool> seastar::file_exists ( std::string_view name )

noexcept

check if a file exists.

Parameters

name	name of the file to check

◆ file_size()

future<uint64_t> seastar::file_size ( std::string_view name )

noexcept

Return the size of a file.

Parameters

name	name of the file to return the size

Note that file_size of a symlink is NOT the size of the symlink - which is the length of the pathname it contains - but rather the size of the file to which it points.

◆ file_stat()

future<stat_data> seastar::file_stat	(	std::string_view	name,
		follow_symlink	fs = `follow_symlink::yes`
	)

noexcept

Return stat information about a file.

Parameters

name	name of the file to return its stat information
fs	a follow_symlink flag to follow symbolic links.

Returns: stat_data of the file identified by name. If name identifies a symbolic link then stat_data is returned either for the target of the link, with follow_symlink::yes, or for the link itself, with follow_symlink::no.

◆ file_system_at()

future<fs_type> seastar::file_system_at ( std::string_view name )

noexcept

Return information about the filesystem where a file is located.

Parameters

name	name of the file to inspect

◆ file_type()

future<std::optional<directory_entry_type> > seastar::file_type	(	std::string_view	name,
		follow_symlink	follow = `follow_symlink::yes`
	)

noexcept

Determine the type of a file (regular file, directory, etc.)

Parameters

name	name of the file for which type information is requested
follow	a follow_symlink flag that determines whether a trailing symbolic link should be followed or not

Returns: a engaged optional with the file type if lookup was successful; a disengaged optional if the file (or one of its parent directories) does not exist; an exceptional future on other errors.

◆ fs_avail()

future<uint64_t> seastar::fs_avail ( std::string_view name )

noexcept

Return space available to unprivileged users in filesystem where a file is located, in bytes.

Parameters

name	name of the file to inspect

◆ fs_free()

future<uint64_t> seastar::fs_free ( std::string_view name )

noexcept

Return free space in filesystem where a file is located, in bytes.

Parameters

name	name of the file to inspect

◆ link_file()

future seastar::link_file	(	std::string_view	oldpath,
		std::string_view	newpath
	)

noexcept

Creates a hard link for a file

Parameters

oldpath	existing file name
newpath	name of link

◆ make_directory()

future seastar::make_directory	(	std::string_view	name,
		file_permissions	permissions = `file_permissions::default_dir_permissions`
	)

noexcept

Creates a new directory.

Parameters

name	name of the directory to create
permissions	optional file permissions of the directory to create.

Note: The directory is not guaranteed to be stable on disk, unless the containing directory is sync'ed.

◆ open_directory()

future< file > open_directory ( std::string_view name )

Parameters

name	name of the directory to open

Returns: a file object representing a directory. The only legal operations are file::list_directory(), file::flush(), and file::close().

◆ open_file_dma() [1/2]

future< file > open_file_dma	(	std::string_view	name,
		open_flags	flags
	)

Parameters

name	the name of the file to open or create
flags	various flags controlling the open process

Returns: a file object, as a future

Note: The file name is not guaranteed to be stable on disk, unless the containing directory is sync'ed.

◆ open_file_dma() [2/2]

future< file > open_file_dma	(	std::string_view	name,
		open_flags	flags,
		file_open_options	options
	)

Parameters

name	the name of the file to open or create
flags	various flags controlling the open process
options	options for opening the file

Returns: a file object, as a future

Note: The file name is not guaranteed to be stable on disk, unless the containing directory is sync'ed.

◆ recursive_touch_directory()

future seastar::recursive_touch_directory	(	std::string_view	name,
		file_permissions	permissions = `file_permissions::default_dir_permissions`
	)

noexcept

Recursively ensures a directory exists

Checks whether each component of a directory exists, and if not, creates it.

Parameters

name	name of the directory to potentially create
permissions	optional file permissions of the directory to create.

Note: This function fsyncs each component created, and is therefore guaranteed to be stable on disk. The provided permissions are applied only on the last component in the path, if it needs to be created, if intermediate directories do not exist, they are created with the default_dir_permissions. If any directory exists, the provided permissions are not applied.

◆ remove_file()

future seastar::remove_file ( std::string_view name )

noexcept

Removes (unlinks) a file or an empty directory

Parameters

name	name of the file or the directory to remove

Note: The removal is not guaranteed to be stable on disk, unless the containing directory is sync'ed.

◆ rename_file()

future seastar::rename_file	(	std::string_view	old_name,
		std::string_view	new_name
	)

noexcept

Renames (moves) a file.

Parameters

old_name	existing file name
new_name	new file name

Note: The rename is not guaranteed to be stable on disk, unless the both containing directories are sync'ed.

◆ sync_directory()

future seastar::sync_directory ( std::string_view name )

noexcept

Synchronizes a directory to disk

Makes sure the modifications in a directory are synchronized in disk. This is useful, for instance, after creating or removing a file inside the directory.

Parameters

name	name of the directory to potentially create

◆ touch_directory()

future seastar::touch_directory	(	std::string_view	name,
		file_permissions	permissions = `file_permissions::default_dir_permissions`
	)

noexcept

Ensures a directory exists

Checks whether a directory exists, and if not, creates it. Only the last component of the directory name is created.

Parameters

name	name of the directory to potentially create
permissions	optional file permissions of the directory to create.

Note: The directory is not guaranteed to be stable on disk, unless the containing directory is sync'ed. If the directory exists, the provided permissions are not applied.

◆ with_file()

template<typename Func >

auto seastar::with_file	(	future< file >	file_fut,
		Func	func
	)

noexcept

Helper for ensuring a file is closed after func is called.

The file provided by the file_fut future is passed to func.

Parameters

file_fut	A future that produces a file
func	A function that uses a file

Returns: the future returned by func, or an exceptional future if either file_fut or closing the file failed.

Examples: file_demo.cc.

◆ with_file_close_on_failure()

template<typename Func >

auto seastar::with_file_close_on_failure	(	future< file >	file_fut,
		Func	func
	)

noexcept

Helper for ensuring a file is closed if func fails.

The file provided by the file_fut future is passed to func.

If func throws an exception E, the file is closed and we return a failed future with E.
If func returns a value V, the file is not closed and we return a future with V. Note that when an exception is not thrown, it is the responsibility of func to make sure the file will be closed. It can close the file itself, return it, or store it somewhere.

Parameters

file_fut	A future that produces a file
func	A function that uses a file

Returns: the future returned by func, or an exceptional future if file_fut failed or a nested exception if closing the file failed.

Examples: file_demo.cc.

Detailed Description

Modules

Classes

Typedefs

Enumerations

Functions

Class Documentation

◆ seastar::directory_entry

◆ seastar::stat_data

◆ seastar::follow_symlink_tag

Enumeration Type Documentation

◆ directory_entry_type

◆ open_flags

Function Documentation

◆ check_direct_io_support()

◆ chmod()

◆ file_accessible()

◆ file_exists()

◆ file_size()

◆ file_stat()

◆ file_system_at()

◆ file_type()

◆ fs_avail()

◆ fs_free()

◆ link_file()

◆ make_directory()

◆ open_directory()

◆ open_file_dma() [1/2]

◆ open_file_dma() [2/2]

◆ recursive_touch_directory()

◆ remove_file()

◆ rename_file()

◆ sync_directory()

◆ touch_directory()

◆ with_file()

◆ with_file_close_on_failure()