rsm_memseg_export_create(3RSM)			      Remote Shared Memory Library Functions			    rsm_memseg_export_create(3RSM)

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  manage-
       ment  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 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 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

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

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

SEE ALSO

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

SunOS 5.11							    8 Apr 2003					    rsm_memseg_export_create(3RSM)