usr/src/man/man2/mmapobj.2

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems Inc. All
   3 .\" Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH MMAPOBJ 2 "Dec 1, 2008"
   8 .SH NAME
   9 mmapobj \- map a file object in the appropriate manner
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/mman.h>
  14
  15 \fBint\fR \fBmmapobj\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIflags\fR, \fBmmapobj_result_t *\fR\fIstorage\fR,
  16      \fBuint_t *\fR\fIelements\fR, \fBvoid *\fR\fIarg\fR);
  17 .fi
  18
  19 .SH PARAMETERS
  20 .sp
  21 .ne 2
  22 .na
  23 \fB\fIfd\fR\fR
  24 .ad
  25 .RS 12n
  26 The open file descriptor for the file to be mapped.
  27 .RE
  28
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIflags\fR\fR
  33 .ad
  34 .RS 12n
  35 Indicates that the default behavior of \fBmmapobj()\fR should be modified
  36 accordingly. Available flags are:
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fBMMOBJ_INTERPRET\fR\fR
  41 .ad
  42 .sp .6
  43 .RS 4n
  44 Interpret the contents of the file descriptor instead of just mapping it as a
  45 single image. This flag can be used only with \fBELF\fR and \fBAOUT\fR files.
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fBMMOBJ_PADDING\fR\fR
  52 .ad
  53 .sp .6
  54 .RS 4n
  55 When mapping in the file descriptor, add an additional mapping before the
  56 lowest mapping and after the highest mapping. The size of this padding is at
  57 least as large as the amount pointed to by \fIarg\fR. These mappings will be
  58 private to the process, will not reserve any swap space and will have no
  59 protections. To use this address space, the protections for it will need to be
  60 changed. This padding request will be ignored for the \fBAOUT\fR format.
  61 .RE
  62
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIstorage\fR\fR
  69 .ad
  70 .RS 12n
  71 A pointer to the \fBmmapobj_result_t\fR array where the mapping data will be
  72 copied out after a successful mapping of \fIfd\fR.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fIelements\fR\fR
  79 .ad
  80 .RS 12n
  81 A pointer to the number of \fBmmapobj_result_t\fR elements pointed to by
  82 \fIstorage\fR.  On return, \fIelements\fR contains the number of mappings
  83 required to fully map the requested object.  If the original value of
  84 \fIelements\fR is too small, \fBE2BIG\fR is returned and \fIelements\fR is
  85 modified to contain the number of mappings necessary.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fIarg\fR\fR
  92 .ad
  93 .RS 12n
  94 A pointer to additional information that might be associated with the specific
  95 request. Only the \fBMMOBJ_PADDING\fR request uses this argument. If
  96 \fBMMOBJ_PADDING\fR is not specified, \fIarg\fR must be \fINULL\fR.
  97 .RE
  98
  99 .SH DESCRIPTION
 100 .sp
 101 .LP
 102 The \fBmmapobj()\fR function establishes a set of mappings between a process's
 103 address space and a file.  By default, \fBmmapobj()\fR maps the whole file as a
 104 single, private, read-only mapping.  The \fBMMOBJ_INTERPRET\fR flag instructs
 105 \fBmmapobj()\fR to attempt to interpret the file and map the file according to
 106 the rules for that file format.  The following \fBELF\fR and \fBAOUT\fR formats
 107 are supported:
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBET_EXEC\fR and \fBAOUT\fR executables\fR
 112 .ad
 113 .sp .6
 114 .RS 4n
 115 This format results in one or more mappings whose size, alignment and
 116 protections are as described by the file's program header information. The
 117 address of each mapping is explicitly defined by the file's program headers.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBET_DYN\fR and \fBAOUT\fR shared objects\fR
 124 .ad
 125 .sp .6
 126 .RS 4n
 127 This format results in one or more mappings whose size, alignment and
 128 protections are as described by the file's program header information. The base
 129 address of the initial mapping is chosen by \fBmmapobj()\fR. The addresses of
 130 adjacent mappings are based off of this base address as defined by the file's
 131 program headers.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBET_REL\fR and \fBET_CORE\fR\fR
 138 .ad
 139 .sp .6
 140 .RS 4n
 141 This format results in a single, read-only mapping that covers the whole file.
 142 The base address of this mapping is chosen by \fBmmapobj()\fR.
 143 .RE
 144
 145 .sp
 146 .LP
 147 The \fBmmapobj()\fR function will not map over any currently used mappings
 148 within the process, except for the case of an \fBELF ET_EXEC\fR file for which
 149 a previous reservation has been made via \fB/dev/null\fR. The most common way
 150 to make such a reservation would be with an \fBmmap()\fR of \fB/dev/null\fR.
 151 .sp
 152 .LP
 153 Mappings created with \fBmmapobj()\fR can be processed individually by other
 154 system calls such as \fBmunmap\fR(2).
 155 .sp
 156 .LP
 157 The \fBmmapobj_result\fR structure contains the following members:
 158 .sp
 159 .in +2
 160 .nf
 161 typedef struct mmapobj_result {
 162       caddr_t         mr_addr;         /* mapping address */
 163       size_t          mr_msize;        /* mapping size */
 164       size_t          mr_fsize;        /* file size */
 165       size_t          mr_offset;       /* offset into file */
 166       uint_t          mr_prot;         /* the protections provided */
 167       uint_t          mr_flags;        /* info on the mapping */
 168 } mmapobj_result_t;
 169 .fi
 170 .in -2
 171
 172 .sp
 173 .LP
 174 The macro \fBMR_GET_TYPE\fR(\fImr_flags\fR) must be used when looking for the
 175 above flags in the value of \fImr_flags\fR.
 176 .sp
 177 .LP
 178 Values for \fImr_flags\fR include:
 179 .sp
 180 .in +2
 181 .nf
 182 MR_PADDING   0x1  /* this mapping represents requested padding */
 183 MR_HDR_ELF   0x2  /* the ELF header is mapped at mr_addr */
 184 MR_HDR_AOU   0x3  /* the AOUT header is mapped at mr_addr */
 185 .fi
 186 .in -2
 187
 188 .sp
 189 .LP
 190 When \fBMR_PADDING\fR is set, \fImr_fsize\fR and \fImr_offset\fR will both be
 191 0.
 192 .sp
 193 .LP
 194 The \fImr_fsize\fR member represents the amount of the file that is mapped into
 195 memory with this mapping.
 196 .sp
 197 .LP
 198 The \fImr_offset\fR member is the offset into the mapping where valid data
 199 begins.
 200 .sp
 201 .LP
 202 The \fImr_msize\fR member represents the size of the memory mapping starting at
 203 \fImr_addr\fR. This size may include unused data prior to \fImr_offset\fR that
 204 exists to satisfy the alignment requirements of this segment. This size may
 205 also include any non-file data that are required to provide \fBNOBITS\fR data
 206 (typically .\fBbss\fR). The system reserves the right to map more than
 207 \fImr_msize\fR bytes of memory but only \fImr_msize\fR bytes will be available
 208 to the caller of \fBmmapobj()\fR.
 209 .SH RETURN VALUES
 210 .sp
 211 .LP
 212 Upon successful completion, 0 is returned and \fIelements\fR contains the
 213 number of program headers that are mapped for \fIfd\fR. The data describing
 214 these elements are copied to storage such that the first \fIelements\fR members
 215 of the storage array contain valid mapping data.
 216 .sp
 217 .LP
 218 On failure, -1 is returned and \fBerrno\fR is set to indicate the error. No
 219 data is copied to storage.
 220 .SH ERRORS
 221 .sp
 222 .LP
 223 The \fBmmapobj()\fR function will fail if:
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBE2BIG\fR\fR
 228 .ad
 229 .RS 14n
 230 The \fIelements\fR argument was not large enough to hold the number of loadable
 231 segments in \fIfd\fR. The \fIelements\fR argument will be modified to contain
 232 the number of segments required.
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBEACCES\fR\fR
 239 .ad
 240 .RS 14n
 241 The file system containing the \fIfd\fR to be mapped does not allow execute
 242 access, or the file descriptor pointed to by \fIfd\fR is not open for reading.
 243 .RE
 244
 245 .sp
 246 .ne 2
 247 .na
 248 \fB\fBEADDRINUSE\fR\fR
 249 .ad
 250 .RS 14n
 251 The mapping requirements overlap an object that is already used by the process.
 252 .RE
 253
 254 .sp
 255 .ne 2
 256 .na
 257 \fB\fBEAGAIN\fR\fR
 258 .ad
 259 .RS 14n
 260 There is insufficient room to reserve swap space for the mapping.
 261 .sp
 262 The file to be mapped is already locked using advisory or mandatory record
 263 locking. See \fBfcntl\fR(2).
 264 .RE
 265
 266 .sp
 267 .ne 2
 268 .na
 269 \fB\fBEBADF\fR\fR
 270 .ad
 271 .RS 14n
 272 The \fIfd\fR argument is not a valid open file descriptor.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fBEFAULT\fR\fR
 279 .ad
 280 .RS 14n
 281 The \fIstorage\fR, \fIarg\fR, or \fIelements\fR argument points to an invalid
 282 address.
 283 .RE
 284
 285 .sp
 286 .ne 2
 287 .na
 288 \fB\fBEINVAL\fR\fR
 289 .ad
 290 .RS 14n
 291 The \fIflags\fR argument contains an invalid flag.
 292 .sp
 293 \fBMMOBJ_PADDING\fR was not specified in \fIflags\fRand \fIarg\fR was non-null.
 294 .RE
 295
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fBENODEV\fR\fR
 300 .ad
 301 .RS 14n
 302 The \fIfd\fR argument refers to an object for which \fBmmapobj()\fR is
 303 meaningless, such as a terminal.
 304 .RE
 305
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fBENOMEM\fR\fR
 310 .ad
 311 .RS 14n
 312 Insufficient memory is available to hold the program headers.
 313 .sp
 314 Insufficient memory is available in the address space to create the mapping.
 315 .RE
 316
 317 .sp
 318 .ne 2
 319 .na
 320 \fB\fBENOTSUP\fR\fR
 321 .ad
 322 .RS 14n
 323 The current user data model does not match the \fIfd\fR to be interpreted;
 324 thus, a 32-bit process that tried to use \fBmmapobj()\fR to interpret a 64-bit
 325 object would return \fBENOTSUP\fR.
 326 .sp
 327 The \fIfd\fR argument is a file whose type can not be interpreted and
 328 \fBMMOBJ_INTERPRET\fR was specified in \fIflags\fR.
 329 .sp
 330 The \fBELF\fR header contains an unaligned \fIe_phentsize\fR value.
 331 .RE
 332
 333 .sp
 334 .ne 2
 335 .na
 336 \fB\fBENOSYS\fR\fR
 337 .ad
 338 .RS 14n
 339 An unsupported filesystem operation was attempted while trying to map in the
 340 object.
 341 .RE
 342
 343 .SH ATTRIBUTES
 344 .sp
 345 .LP
 346 See \fBattributes\fR(5) for descriptions of the following attributes:
 347 .sp
 348
 349 .sp
 350 .TS
 351 box;
 352 c | c
 353 l | l .
 354 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 355 _
 356 Interface Stability     Private
 357 _
 358 MT-Level        Async-Signal-Safe
 359 .TE
 360
 361 .SH SEE ALSO
 362 .sp
 363 .LP
 364 \fBld.so.1\fR(1), \fBfcntl\fR(2), \fBmemcntl\fR(2), \fBmmap\fR(2),
 365 \fBmprotect\fR(2), \fBmunmap\fR(2), \fBelf\fR(3ELF), \fBmadvise\fR(3C),
 366 \fBmlockall\fR(3C), \fBmsync\fR(3C), \fBa.out\fR(4), \fBattributes\fR(5)
 367 .sp
 368 .LP
 369 \fILinker and Libraries Guide\fR