usr/src/man/man3rsm/rsm_memseg_export_create.3rsm

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc.  All rights reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH RSM_MEMSEG_EXPORT_CREATE 3RSM "Apr 8, 2003"
   7 .SH NAME
   8 rsm_memseg_export_create, rsm_memseg_export_destroy, rsm_memseg_export_rebind
   9 \- resource allocation and management functions for export memory segments
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... -lrsm [ \fIlibrary\fR... ]
  14 #include <rsmapi.h>
  15
  16 \fBint\fR \fBrsm_memseg_export_create\fR(
  17      \fBrsmapi_controller_handle_t\fR \fIcontroller\fR,
  18      \fBrsm_memseg_export_handle_t *\fR\fImemseg\fR, \fBvoid *\fR\fIvaddr\fR,
  19      \fBsize_t\fR \fIlength\fR, \fBuint_t\fR \fIflags\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBrsm_memseg_export_destroy\fR(
  25      \fBrsm_memseg_export_handle_t\fR \fImemseg\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBrsm_memseg_export_rebind\fR(
  31      \fBrsm_memseg_export_handle_t\fR \fImemseg\fR,
  32      \fBvoid *\fR\fIvaddr\fR, \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlength\fR);
  33 .fi
  34
  35 .SH DESCRIPTION
  36 .sp
  37 .LP
  38 The  \fBrsm_memseg_export_create()\fR, \fBrsm_memseg_export_destroy()\fR, and
  39 \fBrsm_memseg_export_rebind()\fR functions provide for allocation and
  40 management of resources supporting export  memory segments. Exporting a memory
  41 segment involves the application allocating memory in its virtual address space
  42 through the System V shared memory interface or normal operating system memory
  43 allocation functions. This is followed by the calls to create the export
  44 segment and bind physical pages to back to allocated virtual address space.
  45 .sp
  46 .LP
  47 The \fBrsm_memseg_export_create()\fR creates a new memory segment. Physical
  48 memory pages are allocated and are associated with the segment. The segment
  49 lifetime is the same as the lifetime of the creating process or until a destroy
  50 operation is performed. The \fIcontroller\fR argument is the controller handle
  51 obtained from a prior call to  \fBrsm_get_controller\fR(3RSM). The export
  52 memory segment handle is obtained through the \fImemseg\fR argument for use in
  53 subsequent operations. The \fIvaddr\fR argument specifies the process virtual
  54 address for the segment. It must be aligned according to the controller page
  55 size attribute. The \fIlength\fR argument specifies the size of the segment in
  56 bytes and must be in multiples of the controller page size.  The \fIflags\fR
  57 argument is a bitmask of flags. Possible values are:
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBRSM_ALLOW_REBIND\fR\fR
  62 .ad
  63 .RS 27n
  64 Unbind and rebind is allowed on the segment during its lifetime.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBRSM_CREATE_SEG_DONTWAIT\fR\fR
  71 .ad
  72 .RS 27n
  73 The RSMAPI segment create operations \fBrsm_memseg_export_create()\fR and
  74 \fBrsm_memseg_export_publish\fR(3RSM) should not block for resources and return
  75 \fBRSMERR_INSUFFICIENT_RESOURCES\fR to indicate resource shortage.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBRSM_LOCK_OPS\fR\fR
  82 .ad
  83 .RS 27n
  84 This segment can be used for lock operations.
  85 .RE
  86
  87 .sp
  88 .LP
  89 The \fBrsm_memseg_export_destroy()\fR function deallocates the physical memory
  90 pages associated with the segment and disconnects all importers of the segment.
  91 The \fImemseg\fR argument is the export memory segment handle obtained by a
  92 call to \fBrsm_memseg_export_create()\fR.
  93 .sp
  94 .LP
  95 The \fBrsm_memseg_export_rebind()\fR function releases the current backing
  96 pages associated with the segment and allocates new physical memory pages. This
  97 operation is transparent to the importers of the segment.  It is the
  98 responsibility of the application to prevent data access to the export segment
  99 until the rebind operation has completed. Segment data access during rebind
 100 does not cause a system failure but data content results are undefined. The
 101 \fImemseg\fR argument is the export segment handle pointer obtained from
 102 \fBrsm_memseg_export_create()\fR. The \fIvaddr\fR argument must be aligned with
 103 respect to the page size attribute of the controller. The \fIlength\fR argument
 104 modulo controller page size must be 0. The \fIoff\fR argument is currently
 105 unused.
 106 .SH RETURN VALUES
 107 .sp
 108 .LP
 109 Upon successful completion, these functions return 0.  Otherwise, an error
 110 value is returned to indicate the error.
 111 .SH ERRORS
 112 .sp
 113 .LP
 114 The \fBrsm_memseg_export_create()\fR, \fBrsm_memseg_export_destroy()\fR, and
 115 \fBrsm_memseg_export_rebind()\fR functions can return the following errors:
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBRSMERR_BAD_SEG_HNDL\fR \fR
 120 .ad
 121 .RS 24n
 122 Invalid segment handle.
 123 .RE
 124
 125 .sp
 126 .LP
 127 The \fBrsm_memseg_export_create()\fR and \fBrsm_memseg_export_rebind()\fR
 128 functions can return the following errors:
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBRSMERR_BAD_CTLR_HNDL\fR \fR
 133 .ad
 134 .sp .6
 135 .RS 4n
 136 Invalid controller handle.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBRSMERR_CTLR_NOT_PRESENT\fR \fR
 143 .ad
 144 .sp .6
 145 .RS 4n
 146 Controller not present.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBRSMERR_BAD_LENGTH\fR \fR
 153 .ad
 154 .sp .6
 155 .RS 4n
 156 Length zero or length exceeds controller limits.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBRSMERR_BAD_ADDR\fR \fR
 163 .ad
 164 .sp .6
 165 .RS 4n
 166 Invalid address.
 167 .RE
 168
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBRSMERR_INSUFFICIENT_MEM\fR \fR
 173 .ad
 174 .sp .6
 175 .RS 4n
 176 Insufficient memory.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBRSMERR_INSUFFICIENT_RESOURCES\fR \fR
 183 .ad
 184 .sp .6
 185 .RS 4n
 186 Insufficient resources.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBRSMERR_PERM_DENIED\fR \fR
 193 .ad
 194 .sp .6
 195 .RS 4n
 196 Permission denied.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBRSMERR_NOT_CREATOR\fR \fR
 203 .ad
 204 .sp .6
 205 .RS 4n
 206 Not creator of segment.
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBRSMERR_REBIND_NOT_ALLOWED\fR \fR
 213 .ad
 214 .sp .6
 215 .RS 4n
 216 Rebind not allowed.
 217 .RE
 218
 219 .sp
 220 .LP
 221 The \fBrsm_memseg_export_create()\fR function can return the following errors:
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBRSMERR_BAD_MEM_ALIGNMENT\fR\fR
 226 .ad
 227 .RS 28n
 228 The address is not aligned on a page boundary.
 229 .RE
 230
 231 .sp
 232 .LP
 233 The \fBrsm_memseg_export_rebind()\fR function can return the following errors:
 234 .sp
 235 .ne 2
 236 .na
 237 \fB\fBRSMERR_INTERRUPTED\fR\fR
 238 .ad
 239 .RS 22n
 240 The operation was interrupted by a signal.
 241 .RE
 242
 243 .sp
 244 .LP
 245 The \fBrsm_memseg_export_destroy()\fR function can return the following errors:
 246 .sp
 247 .ne 2
 248 .na
 249 \fB\fBRSMERR_POLLFD_IN_USE\fR \fR
 250 .ad
 251 .RS 25n
 252 Poll file descriptor in use.
 253 .RE
 254
 255 .SH USAGE
 256 .sp
 257 .LP
 258 Exporting a memory segment involves the application allocating memory in its
 259 virtual address space through the System V Shared Memory interface or other
 260 normal operating system memory allocation methods such as \fBvalloc()\fR ( see
 261 \fBmalloc\fR(3C)) or \fBmmap\fR(2). Memory for a file mapped with \fBmmap()\fR
 262 must be mapped \fBMAP_PRIVATE\fR.
 263 .SH ATTRIBUTES
 264 .sp
 265 .LP
 266 See \fBattributes\fR(5) for descriptions of the following attributes:
 267 .sp
 268
 269 .sp
 270 .TS
 271 box;
 272 c | c
 273 l | l .
 274 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 275 _
 276 Interface Stability     Unstable
 277 _
 278 MT-Level        MT-Safe
 279 .TE
 280
 281 .SH SEE ALSO
 282 .sp
 283 .LP
 284 \fBrsm_get_controller\fR(3RSM), \fBrsm_memseg_export_publish\fR(3RSM),
 285 \fBattributes\fR(5)