Wrapper for memory map operations. More...

#include <MapFile.hpp>

Inheritance diagram for OksSystem::MapFile:

Collaboration diagram for OksSystem::MapFile:

Public Member Functions
	MapFile (const std::string &file, size_t size, size_t offset, bool read_mode, bool write_mode, mode_t permissions=0666)

	~MapFile ()

void	zero () const
	builds a zeroed file with correct length

void	map ()
	maps the file in memory

void	unmap ()
	unmaps the file

bool	is_mapped () const
	is the file mopped im memory

bool	is_loaded () const throw ()
	is the map loaded in memory

void *	address () const throw ()
	the address of the memory mapped file

size_t	memory_size () const throw ()
	the size of the map

OksSystem::Descriptor *	fd () const throw ()
	the file descriptor. This method returns a valid pointer only if called after map().

Public Member Functions inherited from OksSystem::File
	File (const std::string &name)

	File (const char *name)

	File (const File &other)

virtual	~File ()

	operator std::string () const throw ()

	operator const char * () const throw ()

	operator bool () const throw ()

bool	equals (const File &other) const throw ()
	compare two files *‍/

	operator size_t () const

const std::string &	full_name () const throw ()
	full name for file *‍/

const char *	c_full_name () const throw ()

std::string	short_name () const throw ()
	short name for file *‍/

std::string	parent_name () const throw ()
	path of directory containing file *‍/

std::string	extension () const throw ()
	extension for file *‍/

int	depth () const throw ()
	depth of the file *‍/

OksSystem::File	parent () const
	parent of the current file *‍/

OksSystem::File	child (const std::string &name) const
	named child of the current directory *‍/

OksSystem::File	temporary (const std::string &prefix) const

bool	exists () const throw ()
	does the file exist *‍/

mode_t	permissions () const
	permissions for the file *‍/

std::string	pretty_permissions () const
	pretty permissions for the file *‍/

size_t	size () const
	size of file *‍/

uid_t	owner_id () const
	owner id of file *‍/

User	owner () const
	owner of the file *‍/

gid_t	group () const
	group of file *‍/

bool	is_regular () const
	is the file a directory *‍/

bool	is_directory () const
	is the file a regular file *‍/

bool	is_fifo () const
	is the file a named pipe *‍/

std::string	file_type () const
	type of the file *‍/

file_list_t	directory () const
	list of file in directory *‍/

void	unlink () const
	deletes (unlinks) file *‍/

void	rmdir () const
	deletes directory *‍/

void	remove () const
	recursively delete files and directories *‍/

void	rename (const File &other) const
	rename or moves the file *‍/

void	permissions (mode_t permissions) const
	sets the type of the file *‍/

void	make_dir (mode_t permissions) const
	creates a directory *‍/

void	make_path (mode_t permissions) const
	creates a full path *‍/

void	make_fifo (mode_t permissions) const
	creates a FIFO (named pipe) *‍/

void	ensure_path (mode_t permissions) const
	creates the parent path *‍/

std::istream *	input () const
	returns an input stream from the file*‍/

std::ostream *	output (bool append=false) const
	returns an output stream to the file*‍/

Protected Member Functions
void	open_fd ()
	opens the file descriptor for the map

void	close_fd ()
	closes the file descriptor for the map

void	map_mem ()
	maps the file into memory

void	unmap_mem ()
	unmaps the file into memory

Protected Member Functions inherited from OksSystem::File
void	set_name (const std::string &name)
	sets the name of the file *‍/

mode_t	get_mode () const
	get mode associated with file (permission + type) *‍/

Protected Attributes
void *	m_map_address
	the address of the map in memory

size_t	m_map_size
	the size of the map

size_t	m_map_offset
	offset in the file of the map

Descriptor *	m_map_descriptor
	internal file descriptor

mode_t	m_map_permission
	permissions associated with the file

bool	m_map_read
	is the map readable

bool	m_map_write
	is the map writable

bool	m_is_mapped
	is the file mapped in memory

Protected Attributes inherited from OksSystem::File
std::string	m_full_name
	full name (path) of the file *‍/

Static Private Attributes
static const char *const	MAP_LOAD_MSG
	message pattern - map is loaded

static const char *const	MAP_NOT_LOAD_MSG
	message pattern - map is not loaded

static const char *const	PAGE_SIZE_MSG
	message pattern - illegal page size

static const char *const	READ_OR_WRITE_MSG
	message pattern - map mode is neither read nor write

static const char *const	MAP_NOT_WRITE_MSG
	message pattern - map is not writable

Additional Inherited Members
Public Types inherited from OksSystem::File
typedef std::vector< OksSystem::File >	file_list_t

Static Public Member Functions inherited from OksSystem::File
static std::string	protocol (const std::string &url) throw ()
	extracts the protocol part of an url *‍/

static std::string	extension (const std::string &url) throw ()
	extracts the extension of a path or an url *‍/

static std::string	uri (const std::string &url) throw ()
	extracts the local path of an url *‍/

static std::string	short_name (const std::string &url) throw ()
	extracts the short file name of an url *‍/

static int	depth (const std::string &path) throw ()
	calculates depth of a path *‍/

static std::string	first_line (const std::string &text)
	extracts the first line of a text *‍/

static File	from_url (const std::string &url)
	build a file out of an URL *‍/

static std::string	working_directory ()
	current directory of process *‍/

static void	working_directory (const File &dir)
	set working directory of process *‍/

static std::string	expand_home (const std::string path)
	resolve home directory *‍/

static std::string	pretty_permissions (mode_t permissions)
	pretty prints permissions *‍/

static std::string	to_string (mode_t permissions) throw ()
	converts permission to string *‍/

static std::string	pretty_open_flag (int flags)
	pretty prints open flags *‍/

static std::string	pretty_size (size_t size, bool cut_small)
	pretty prints a file size *‍/

Static Public Attributes inherited from OksSystem::File
static const char *const	FILE_FLAG_STR = "-rwxS"
	column headers for display of permissions *‍/

static const char *const	FILE_PROTOCOL = "file"
	string for the file protocol *‍/

Static Protected Member Functions inherited from OksSystem::File
static int	unit (int u)
	calculates the value of a computer unit of order n (i.e KB,GB, etc *‍/

Static Protected Attributes inherited from OksSystem::File
static const char *const	HUMAN_SIZE_STR [] = { "B", "KB", "MB", "GB" }
	strings for pretty printing file sizes *‍/

static const char *const	HUMAN_OPEN_STR [] = { "READ", "WRITE", "NOBLOCK", "APPEND", "CREATE", "TRUNCATE","EXCLUSIVE" }
	strings for pretty printing open flags *‍/

static const int	KILOBYTE = 1024
	number of bytes in a kilobyte *‍/

static const char *const	FILE_COMMAND_PATH = "/usr/bin/file"

Detailed Description

Wrapper for memory map operations.

This class offers facilities to handle memory mapped files. They can be used to map a file into memory

Author: Matthias Wiesmann

Version: 1.0

Definition at line 26 of file MapFile.hpp.

Constructor & Destructor Documentation

◆ MapFile()

OksSystem::MapFile::MapFile	(	const std::string &	name,
		size_t	s,
		size_t	o,
		bool	read_mode,
		bool	write_mode,
		mode_t	perm = 0666 )

Builds a memory mapped file.

Parameters

name	the path of the file to map.
size	the size of the region to memory map - should be a multiple of the pagesize.
offset	the offset in the file - should be a multiple of pagesize.
read_mode	should the map be read from the file.
write_mode	should the map be writable.
permissions	the permissions associated with the file

Definition at line 31 of file MapFile.cpp.

                                                                                                                 : File(name) {
    ERS_PRECONDITION((read_mode || write_mode)); 
    const int page_size = getpagesize();
    ERS_PRECONDITION((s % page_size)==0);
    ERS_PRECONDITION((o % page_size)==0);
    (void) page_size;// to suppress warning when asserts are disabled
    m_map_read = read_mode;
    m_map_write = write_mode;
    m_map_permission = perm;
    m_map_size = s;
    m_map_offset = o;
    m_map_address = 0;
    m_map_descriptor = 0;
    m_is_mapped = false;
} // MapFile

◆ ~MapFile()

OksSystem::MapFile::~MapFile ( )

Destructor - the file should be unmapped before destruction.

Definition at line 50 of file MapFile.cpp.

                           {
    if (m_map_descriptor!=0) {
    close_fd(); 
    } // file descriptor open 
} // ~MapFile

Member Function Documentation

◆ address()

void * OksSystem::MapFile::address	(		)	const
throw	(	)

the address of the memory mapped file

Gives the actual address of the map in memory. If the file is not yet mapped, this will be 0.

Returns: point to the start address of the mapped file in memory.

Definition at line 167 of file MapFile.cpp.

                                              { 
    return m_map_address;
} // address

◆ close_fd()

void OksSystem::MapFile::close_fd ( )

protected

closes the file descriptor for the map

Closes the file descriptor associated with the memory map.

Exceptions

CloseFail if the close okssystem call fails

Definition at line 70 of file MapFile.cpp.

                                {
    m_map_descriptor->close(); 
    delete(m_map_descriptor);
    m_map_descriptor = 0;
} // close_fd

◆ fd()

OksSystem::Descriptor * OksSystem::MapFile::fd	(		)	const
throw	(	)

the file descriptor. This method returns a valid pointer only if called after map().

Definition at line 185 of file MapFile.cpp.

                                                        {
  return m_map_descriptor;
}

◆ is_loaded()

bool OksSystem::MapFile::is_loaded	(		)	const
throw	(	)

is the map loaded in memory

Definition at line 157 of file MapFile.cpp.

                                               {
    return (m_map_address!=0);
} // is_loaded

◆ is_mapped()

bool OksSystem::MapFile::is_mapped ( ) const

is the file mopped im memory

Returns if the file is mapped or not in memory

Definition at line 181 of file MapFile.cpp.

                                       {
  return m_is_mapped;
}

◆ map()

void OksSystem::MapFile::map ( )

maps the file in memory

Maps the file into memory. This is done first by opening the file descriptor for the file, then doing the actual map.

Exceptions

OpenFail	error while opening the file
MMapFail	error while mapping the file

Definition at line 141 of file MapFile.cpp.

                           {
    open_fd();
    map_mem(); 
} // map 

◆ map_mem()

void OksSystem::MapFile::map_mem ( )

protected

maps the file into memory

Internal method - does the actual memory mapping.

Exceptions

MMapFail	if the `mmap` operation succeeded
Precondition	if the file descriptor is not valid.

Definition at line 81 of file MapFile.cpp.

                               {
    ERS_PRECONDITION(m_map_descriptor); 
    int prot = 0;
    int flags = MAP_FILE | MAP_SHARED;
    if (m_map_read)  { 
    prot|=PROT_READ; 
    } 
    if (m_map_write) { 
    prot|=PROT_WRITE;
    }
    m_map_address = ::mmap(0,m_map_size,prot,flags,*m_map_descriptor,m_map_offset); 
    if (m_map_address==MAP_FAILED || m_map_address==0) {
        m_is_mapped = false;
    std::string message = "on file " + this->full_name();
    throw OksSystem::OksSystemCallIssue( ERS_HERE, errno, "mmap", message.c_str() ); 
    } /* map_failed */ else {
        m_is_mapped = true;
    }
} // map_mem

◆ memory_size()

size_t OksSystem::MapFile::memory_size	(		)	const
throw	(	)

the size of the map

Gives the actual size of the map in memory.

Returns: the size of the memory region

Definition at line 175 of file MapFile.cpp.

                                                    { 
    return m_map_size;
} // memory_size

◆ open_fd()

void OksSystem::MapFile::open_fd ( )

protected

opens the file descriptor for the map

Opens the file descriptor associated with the memory map.

Exceptions

OpenFail if the open okssystem call fails

Definition at line 60 of file MapFile.cpp.

                               {
    const int flags = OksSystem::Descriptor::flags(m_map_read,m_map_write);
    m_map_descriptor = new OksSystem::Descriptor(this, flags,m_map_permission);
} // open_fd 

◆ unmap()

void OksSystem::MapFile::unmap ( )

unmaps the file

Unmaps the file from memory This is done first by unmapping the file, then closing the file-descriptor.

Exceptions

CloseFail	error while closing the file.
MUnmapFail	error while unmapping the file.

Definition at line 152 of file MapFile.cpp.

                             {
    unmap_mem();
    close_fd(); 
} // unmap

◆ unmap_mem()

void OksSystem::MapFile::unmap_mem ( )

protected

unmaps the file into memory

Internal method - does the actual memory unmapping.

Exceptions

MUnmapFail if the munmap operation fails.

Definition at line 105 of file MapFile.cpp.

                                {
    ERS_PRECONDITION(m_map_address!=0);
    const int status = munmap(m_map_address,m_map_size);
    if (status<0) {
      m_is_mapped = true;
      std::string message = "on file " + this->full_name();
      throw OksSystem::OksSystemCallIssue( ERS_HERE, errno, "munmap", message.c_str() );
    } else {
      m_is_mapped = false;
    }
} // unmap_mem

◆ zero()

void OksSystem::MapFile::zero ( ) const

builds a zeroed file with correct length

Creates a zero filled file with correct length

Definition at line 120 of file MapFile.cpp.

                                  {
    ERS_ASSERT(m_map_write==true); 
    const int flags = OksSystem::Descriptor::flags(false,true); 
    OksSystem::Descriptor fd(this, flags,m_map_permission);
    const int page_size = ::getpagesize();
    const int page_num = (m_map_size+m_map_offset) / page_size;
    void *buffer= calloc(1,page_size);
    for(int i=0;i<page_num;i++) {
    fd.write(buffer,page_size); 
    } // for
    free(buffer);
    fd.close(); 
} // zero 

Member Data Documentation

◆ m_is_mapped

bool OksSystem::MapFile::m_is_mapped

protected

is the file mapped in memory

Definition at line 56 of file MapFile.hpp.

◆ m_map_address

void* OksSystem::MapFile::m_map_address

protected

the address of the map in memory

Definition at line 49 of file MapFile.hpp.

◆ m_map_descriptor

Descriptor* OksSystem::MapFile::m_map_descriptor

protected

internal file descriptor

Definition at line 52 of file MapFile.hpp.

◆ m_map_offset

size_t OksSystem::MapFile::m_map_offset

protected

offset in the file of the map

Definition at line 51 of file MapFile.hpp.

◆ m_map_permission

mode_t OksSystem::MapFile::m_map_permission

protected

permissions associated with the file

Definition at line 53 of file MapFile.hpp.

◆ m_map_read

bool OksSystem::MapFile::m_map_read

protected

is the map readable

Definition at line 54 of file MapFile.hpp.

◆ m_map_size

size_t OksSystem::MapFile::m_map_size

protected

the size of the map

Definition at line 50 of file MapFile.hpp.

◆ m_map_write

bool OksSystem::MapFile::m_map_write

protected

is the map writable

Definition at line 55 of file MapFile.hpp.

◆ MAP_LOAD_MSG

const char* const OksSystem::MapFile::MAP_LOAD_MSG

staticprivate

message pattern - map is loaded

Definition at line 60 of file MapFile.hpp.

◆ MAP_NOT_LOAD_MSG

const char* const OksSystem::MapFile::MAP_NOT_LOAD_MSG

staticprivate

message pattern - map is not loaded

Definition at line 61 of file MapFile.hpp.

◆ MAP_NOT_WRITE_MSG

const char* const OksSystem::MapFile::MAP_NOT_WRITE_MSG

staticprivate

message pattern - map is not writable

Definition at line 64 of file MapFile.hpp.

◆ PAGE_SIZE_MSG

const char* const OksSystem::MapFile::PAGE_SIZE_MSG

staticprivate

message pattern - illegal page size

Definition at line 62 of file MapFile.hpp.

◆ READ_OR_WRITE_MSG

const char* const OksSystem::MapFile::READ_OR_WRITE_MSG

staticprivate

message pattern - map mode is neither read nor write

Definition at line 63 of file MapFile.hpp.

The documentation for this class was generated from the following files:

/github/workspace/dunedaq/sourcecode/okssystem/include/okssystem/MapFile.hpp
/github/workspace/dunedaq/sourcecode/okssystem/src/MapFile.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MapFile()

◆ ~MapFile()

Member Function Documentation

◆ address()

◆ close_fd()

◆ fd()

◆ is_loaded()

◆ is_mapped()

◆ map()

◆ map_mem()

◆ memory_size()

◆ open_fd()

◆ unmap()

◆ unmap_mem()

◆ zero()

Member Data Documentation

◆ m_is_mapped

◆ m_map_address

◆ m_map_descriptor

◆ m_map_offset

◆ m_map_permission

◆ m_map_read

◆ m_map_size

◆ m_map_write

◆ MAP_LOAD_MSG

◆ MAP_NOT_LOAD_MSG

◆ MAP_NOT_WRITE_MSG

◆ PAGE_SIZE_MSG

◆ READ_OR_WRITE_MSG