Memory-mapped file regions

Map a whole file (or an open file handle) into the process address space as a single contiguous byte buffer. More...

Files
file	rmemfile.h
	Memory-mapped file API.

Macros
#define	r_mem_file_ref   r_ref_ref
	Acquire a new reference to file.
#define	r_mem_file_unref   r_ref_unref
	Release a reference to file; unmaps when the last drops.

Typedefs
typedef struct RMemFile	RMemFile
	Opaque handle to a memory-mapped file region.

Enumerations
enum	RMemProt { R_MEM_PROT_NONE = 0x0 , R_MEM_PROT_READ = 0x1 , R_MEM_PROT_WRITE = 0x2 , R_MEM_PROT_EXEC = 0x4 }
	Page-level protection flags for the mapping. More...

Functions
RMemFile *	r_mem_file_new (const rchar *file, RMemProt prot, rboolean writeback)
	Map file into memory by pathname.
RMemFile *	r_mem_file_new_from_handle (RIOHandle handle, RMemProt prot, rboolean writeback)
	Map an already-opened file handle into memory.
rsize	r_mem_file_get_size (RMemFile *file)
	Size of the mapped region in bytes.
rpointer	r_mem_file_get_mem (RMemFile *file)
	Pointer to the first byte of the mapped region.

Detailed Description

Map a whole file (or an open file handle) into the process address space as a single contiguous byte buffer.

Typedef Documentation

RMemFile

typedef struct RMemFile RMemFile

Opaque handle to a memory-mapped file region.

Refcounted; obtain a new reference with r_mem_file_ref, release with r_mem_file_unref. The underlying mapping is torn down when the last reference drops.

Enumeration Type Documentation

RMemProt

enum RMemProt

Page-level protection flags for the mapping.

Combined with bitwise-OR. Mirrors POSIX PROT_* and Win32 PAGE_* semantics. R_MEM_PROT_WRITE on its own is rarely useful - pair with R_MEM_PROT_READ.

Enumerator
R_MEM_PROT_NONE	No access.
R_MEM_PROT_READ	Pages may be read.
R_MEM_PROT_WRITE	Pages may be written.
R_MEM_PROT_EXEC	Pages may be executed.

Function Documentation

r_mem_file_get_mem()

rpointer r_mem_file_get_mem

(

RMemFile *

file

)

Pointer to the first byte of the mapped region.

The returned pointer is valid until the last RMemFile reference is dropped. May be NULL for empty files or if the mapping failed silently (e.g. platform without mmap and no Win32 path).

Parameters

file	Mapped file (may be NULL, returns NULL).

Returns

Pointer to the first mapped byte.

r_mem_file_get_size()

rsize r_mem_file_get_size

(

RMemFile *

file

)

Size of the mapped region in bytes.

Parameters

file	Mapped file (may be NULL, returns 0).

Returns

File size in bytes.

r_mem_file_new()

RMemFile * r_mem_file_new	(	const rchar *	file,
		RMemProt	prot,
		rboolean	writeback
	)

Map file into memory by pathname.

Opens file, maps it, and closes the file handle (the kernel keeps the mapping alive). Equivalent to r_mem_file_new_from_handle with the file-open step folded in.

Parameters

file	Filesystem path.
prot	Page-protection flags (see RMemProt).
writeback	If TRUE and prot includes R_MEM_PROT_WRITE, writes propagate back to the file (MAP_SHARED on POSIX). If FALSE writes go to a private copy (MAP_PRIVATE).

Returns

A new RMemFile reference, or NULL on open / map failure.

r_mem_file_new_from_handle()

RMemFile * r_mem_file_new_from_handle	(	RIOHandle	handle,
		RMemProt	prot,
		rboolean	writeback
	)

Map an already-opened file handle into memory.

Lets the caller control the open flags (e.g. unicode paths, O_DIRECT, OS-specific share modes). The mapping outlives the handle's open state - on Win32 the CreateFileMapping object keeps the file alive; on POSIX the kernel reference counts the inode.

Parameters

handle	An open file handle (rlib's RIOHandle type).
prot	Page-protection flags.
writeback	Write-back behaviour (see r_mem_file_new).

Returns

A new RMemFile reference, or NULL on map failure.