Seastar
High performance C++ framework for concurrent servers
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
Modules | Classes | Typedefs | Enumerations | Functions
File Input/Output

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::group_details
 Group details from the system group database. 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
 

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<std::invocable< file & > Func>
requires std::is_nothrow_move_constructible_v<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<std::invocable< file & > Func>
requires std::is_nothrow_move_constructible_v<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_dataseastar::file_stat (std::string_view name, follow_symlink fs=follow_symlink::yes) noexcept
 
future< std::optional< struct group_details > > seastar::getgrnam (std::string_view name)
 
future seastar::chown (std::string_view filepath, uid_t owner, gid_t group)
 
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_typeseastar::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< fileopen_file_dma (std::string_view name, open_flags flags) noexcept
 
future< fileopen_file_dma (std::string_view name, open_flags flags, file_open_options options) noexcept
 
future< fileopen_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::group_details

struct seastar::group_details
Class Members
__gid_t group_id
vector< sstring > group_members
sstring group_name
sstring group_passwd

◆ 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 class seastar::directory_entry_type
strong

Enumeration describing the type of a directory entry being listed.

See also
file::list_directory()

◆ open_flags

enum class 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
paththe 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
namename of the file ot directory to change
permissionspermissions to set

◆ chown()

future seastar::chown ( std::string_view  filepath,
uid_t  owner,
gid_t  group 
)

Change the owner and group of file. This is a wrapper around chown syscall. The function throws std::system_error, when the chown syscall fails.

Parameters
filepath
owner
group

◆ file_accessible()

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

Check file access.

Parameters
namename of the file to check
flagsbit 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
namename 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
namename 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
namename of the file to return its stat information
fsa 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
namename 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
namename of the file for which type information is requested
followa 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
namename 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
namename of the file to inspect

◆ getgrnam()

future< std::optional< struct group_details > > seastar::getgrnam ( std::string_view  name)

Wrapper around getgrnam_r. If the provided group name does not exist in the group database, this call will return an empty optional. If the provided group name exists in the group database, the optional returned will contain the struct group_details information. When an unexpected error is thrown by the getgrnam_r libc call, this function throws std::system_error with std::error_code.

Parameters
groupnamename of the group
Returns
optional struct group_details of the group identified by name. struct group_details has details of the group from the group database.

◆ link_file()

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

Creates a hard link for a file

Parameters
oldpathexisting file name
newpathname 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
namename of the directory to create
permissionsoptional 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)
related

Opens a directory.

Parameters
namename 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 
)
related

Opens or creates a file. The "dma" in the name refers to the fact that data transfers are unbuffered and uncached.

Parameters
namethe name of the file to open or create
flagsvarious 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.
Examples
file_demo.cc.

◆ open_file_dma() [2/2]

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

Opens or creates a file. The "dma" in the name refers to the fact that data transfers are unbuffered and uncached.

Parameters
namethe name of the file to open or create
flagsvarious flags controlling the open process
optionsoptions 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
namename of the directory to potentially create
permissionsoptional 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
namename 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_nameexisting file name
new_namenew 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
namename 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
namename of the directory to potentially create
permissionsoptional 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<std::invocable< file & > Func>
requires std::is_nothrow_move_constructible_v<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_futA future that produces a file
funcA 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<std::invocable< file & > Func>
requires std::is_nothrow_move_constructible_v<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_futA future that produces a file
funcA 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.