Tribblix: manual page: rsm_memseg_export

RSM_MEMSEG_EXPORT_CREATE(3RSM) Remote Shared Memory Library Functions

NAME

rsm_memseg_export_create, rsm_memseg_export_destroy,
rsm_memseg_export_rebind - resource allocation and management
functions for export memory segments

SYNOPSIS

cc [ flag... ] file... -lrsm [ library... ]
#include <rsmapi.h>

int rsm_memseg_export_create(
rsmapi_controller_handle_t controller,
rsm_memseg_export_handle_t *memseg, void *vaddr,
size_t length, uint_t flags);

int rsm_memseg_export_destroy(
rsm_memseg_export_handle_t memseg);

int rsm_memseg_export_rebind(
rsm_memseg_export_handle_t memseg,
void *vaddr, offset_t off, size_t length);

DESCRIPTION

The rsm_memseg_export_create(), rsm_memseg_export_destroy(), and
rsm_memseg_export_rebind() functions provide for allocation and
management of resources supporting export memory segments. Exporting
a memory segment involves the application allocating memory in its
virtual address space through the System V shared memory interface or
normal operating system memory allocation functions. This is followed
by the calls to create the export segment and bind physical pages to
back to allocated virtual address space.

The rsm_memseg_export_create() creates a new memory segment. Physical
memory pages are allocated and are associated with the segment. The
segment lifetime is the same as the lifetime of the creating process
or until a destroy operation is performed. The controller argument is
the controller handle obtained from a prior call to
rsm_get_controller(3RSM). The export memory segment handle is
obtained through the memseg argument for use in subsequent
operations. The vaddr argument specifies the process virtual address
for the segment. It must be aligned according to the controller page
size attribute. The length argument specifies the size of the segment
in bytes and must be in multiples of the controller page size. The
flags argument is a bitmask of flags. Possible values are:

RSM_ALLOW_REBIND
Unbind and rebind is allowed on the
segment during its lifetime.

RSM_CREATE_SEG_DONTWAIT
The RSMAPI segment create operations
rsm_memseg_export_create() and
rsm_memseg_export_publish(3RSM) should not
block for resources and return
RSMERR_INSUFFICIENT_RESOURCES to indicate
resource shortage.

RSM_LOCK_OPS
This segment can be used for lock
operations.

The rsm_memseg_export_destroy() function deallocates the physical
memory pages associated with the segment and disconnects all
importers of the segment. The memseg argument is the export memory
segment handle obtained by a call to rsm_memseg_export_create().

The rsm_memseg_export_rebind() function releases the current backing
pages associated with the segment and allocates new physical memory
pages. This operation is transparent to the importers of the segment.
It is the responsibility of the application to prevent data access to
the export segment until the rebind operation has completed. Segment
data access during rebind does not cause a system failure but data
content results are undefined. The memseg argument is the export
segment handle pointer obtained from rsm_memseg_export_create(). The
vaddr argument must be aligned with respect to the page size
attribute of the controller. The length argument modulo controller
page size must be 0. The off argument is currently unused.

RETURN VALUES

Upon successful completion, these functions return 0. Otherwise, an
error value is returned to indicate the error.

ERRORS

The rsm_memseg_export_create(), rsm_memseg_export_destroy(), and
rsm_memseg_export_rebind() functions can return the following errors:

RSMERR_BAD_SEG_HNDL
Invalid segment handle.

The rsm_memseg_export_create() and rsm_memseg_export_rebind()
functions can return the following errors:

RSMERR_BAD_CTLR_HNDL

Invalid controller handle.

RSMERR_CTLR_NOT_PRESENT

Controller not present.

RSMERR_BAD_LENGTH

Length zero or length exceeds controller limits.

RSMERR_BAD_ADDR

Invalid address.

RSMERR_INSUFFICIENT_MEM

Insufficient memory.

RSMERR_INSUFFICIENT_RESOURCES

Insufficient resources.

RSMERR_PERM_DENIED

Permission denied.

RSMERR_NOT_CREATOR

Not creator of segment.

RSMERR_REBIND_NOT_ALLOWED

Rebind not allowed.

The rsm_memseg_export_create() function can return the following
errors:

RSMERR_BAD_MEM_ALIGNMENT
The address is not aligned on a page
boundary.

The rsm_memseg_export_rebind() function can return the following
errors:

RSMERR_INTERRUPTED
The operation was interrupted by a signal.

The rsm_memseg_export_destroy() function can return the following
errors:

RSMERR_POLLFD_IN_USE
Poll file descriptor in use.

USAGE

Exporting a memory segment involves the application allocating memory
in its virtual address space through the System V Shared Memory
interface or other normal operating system memory allocation methods
such as valloc() ( see malloc(3C)) or mmap(2). Memory for a file
mapped with mmap() must be mapped MAP_PRIVATE.

ATTRIBUTES