rsm_memseg_export_crRemoteRShared Memory Libraryrsm_memseg_export_create(3RSM)NAME
rsm_memseg_export_create, rsm_memseg_export_destroy, rsm_mem‐
seg_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 manage‐
ment of resources supporting export memory segments. Exporting a mem‐
ory 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_con‐
troller(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 mul‐
tiples 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 mem‐
ory 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 con‐
tent 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 con‐
troller 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 sig‐
nal.
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 inter‐
face 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
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Unstable │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │MT-Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOrsm_get_controller(3RSM), rsm_memseg_export_publish(3RSM),
attributes(5)SunOS 5.10 8 Apr 2003 rsm_memseg_export_create(3RSM)
