Memory-Mapped-File

int unittest_io_mmfile( void )

Test mapping of file into memory.

int init_mmfile(     /*out*/mmfile_t  * mfile,        const  char  * file_path,        off_t  file_offset,        size_t  size,        accessmode_e  mode,        const struct directory_t *  relative_to  /*0  =  >current_working_directory*/ )

Opens a new file and maps it to memory.  Parameter file_path is considered relative to relative_to instead of the current working directory if relative_to is set to a value != 0 and file_path is a relative path

Files can be mapped into memory only page by page.  If the file size is not a multiple of pagesize_vm all memory of the last mapped page which is beyond the size of the underlying file is filled with 0, and writes to that region are not written to the file.

Parameter

int initfromio_mmfile( /*out*/mmfile_t  * mfile, sys_iochannel_t  fd, off_t  file_offset, size_t  size, accessmode_e  mode )

Maps a file referenced by sys_iochannel_t into memory.  The function does the same as init_mmfile except it does not open a file but takes a file descriptor to the already opened file.  The file must always be opened with read access and also write access in case mode contains accessmode_WRITE.

Attention

If the file_offset + size is bigger than the size of the underlying file accessing the memory which has no file backing is undefinded.  The operating system creates a bus error exception in cases where a whole memory page has no backing file object.  If the size is set to 0 no mapping is done at all and mmfile_t is initialized with a 0 (<memblock_FREE>).

int initsplit_mmfile( /*out*/mmfile_t  * destheadmfile, /*out*/mmfile_t  * desttailmfile, size_t  headsize, mmfile_t  * sourcemfile )

Split a memory mapping into two.  After return destheadmfile maps the first headsize bytes. headsize must be a multiple of pagesize_vm. desttailmfile maps the last (size_mmfile(sourcemfile)-headsize) bytes. sourcemfile is set to mmfile_FREE if it is not equal to destheadmfile or desttailmfile.

void initmove_mmfile( /*out*/mmfile_t *  restrict  destmfile, mmfile_t *  restrict  sourcemfile )

Moves content of sourcemfile to destmfile. sourcemfile is also reset to mmfile_FREE.

int free_mmfile( mmfile_t  * mfile )

Frees all mapped memory and closes the file.

bool isfree_mmfile( const  mmfile_t  * mfile )

Returns true if mfile == mmfile_FREE.

uint8_t * addr_mmfile( const  mmfile_t  * mfile )

Returns the lowest address of the mapped memory.  The memory is always mapped in chunks of pagesize_vm.  The memory which can be accessed is at least [addr_mmfile ..  <addr_mmfile>+<size_mmfile>].

size_t size_mmfile( const  mmfile_t  * mfile )

Returns the size of the mapped memory.  The memory which corresponds to the underlying file is exactly [addr_mmfile ..  <addr_mmfile>+<size_mmfile>].

size_t alignedsize_mmfile( const  mmfile_t  * mfile )

Returns the size of the mapped memory.  This value is a multiple of pagesize_vm and it is >= size_mmfile.  The mapped memory region is [addr_mmfile ..  <addr_mmfile>+<alignedsize_mmfile>] but only [addr_mmfile ..  <addr_mmfile>+<size_mmfile>] corresponds to the underlying file.

int seek_mmfile( mmfile_t  * mfile, sys_iochannel_t  fd, off_t  file_offset, accessmode_e  mode )

Use it to change offset of the underlying file mapped into memory.  The file_offset must be a multiple of pagesize_vm -- see also initfromio_mmfile.

Attention

mmfile_t * genericcast_mmfile( void  * obj, IDNAME  nameprefix, TYPEQUALIFIER  qualifier )

Casts a generic object pointer into pointer to memblock_t.  Set qual to const if you want to cast a const pointer.  The object must have two data members with access path “obj->nameprefix##addr” and “obj->nameprefix##size” of the same type as mmfile_t and in the same order.