te
Copyright (c) 2003, Sun Microsystems, Inc. All rights reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
rsm_memseg_export_create, rsm_memseg_export_destroy, rsm_memseg_export_rebind - resource allocation and management functions for export memory segments

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);

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

RSM_CREATE_SEG_DONTWAIT

RSM_LOCK_OPS

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.

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

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

RSMERR_BAD_SEG_HNDL

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

RSMERR_BAD_CTLR_HNDL

RSMERR_CTLR_NOT_PRESENT

RSMERR_BAD_LENGTH

RSMERR_BAD_ADDR

RSMERR_INSUFFICIENT_MEM

RSMERR_INSUFFICIENT_RESOURCES

RSMERR_PERM_DENIED

RSMERR_NOT_CREATOR

RSMERR_REBIND_NOT_ALLOWED

The rsm_memseg_export_create() function can return the following errors:

RSMERR_BAD_MEM_ALIGNMENT

The rsm_memseg_export_rebind() function can return the following errors:

RSMERR_INTERRUPTED

The rsm_memseg_export_destroy() function can return the following errors:

RSMERR_POLLFD_IN_USE

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.

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Unstable
MT-Level	MT-Safe

rsm_get_controller(3RSM), rsm_memseg_export_publish(3RSM), attributes(5)