'\" te
.\" Copyright (c) 2008, 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]
.TH MMAPOBJ 2 "June 20, 2021"
.SH NAME
mmapobj \- map a file object in the appropriate manner
.SH SYNOPSIS
.nf
#include <sys/mman.h>

\fBint\fR \fBmmapobj\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIflags\fR, \fBmmapobj_result_t *\fR\fIstorage\fR,
     \fBuint_t *\fR\fIelements\fR, \fBvoid *\fR\fIarg\fR);
.fi

.SH PARAMETERS
.ne 2
.na
\fB\fIfd\fR\fR
.ad
.RS 12n
The open file descriptor for the file to be mapped.
.RE

.sp
.ne 2
.na
\fB\fIflags\fR\fR
.ad
.RS 12n
Indicates that the default behavior of \fBmmapobj()\fR should be modified
accordingly. Available flags are:
.sp
.ne 2
.na
\fB\fBMMOBJ_INTERPRET\fR\fR
.ad
.sp .6
.RS 4n
Interpret the contents of the file descriptor instead of just mapping it as a
single image. This flag can be used only with \fBELF\fR and \fBAOUT\fR files.
.RE

.sp
.ne 2
.na
\fB\fBMMOBJ_PADDING\fR\fR
.ad
.sp .6
.RS 4n
When mapping in the file descriptor, add an additional mapping before the
lowest mapping and after the highest mapping. The size of this padding is at
least as large as the amount pointed to by \fIarg\fR. These mappings will be
private to the process, will not reserve any swap space and will have no
protections. To use this address space, the protections for it will need to be
changed. This padding request will be ignored for the \fBAOUT\fR format.
.RE

.RE

.sp
.ne 2
.na
\fB\fIstorage\fR\fR
.ad
.RS 12n
A pointer to the \fBmmapobj_result_t\fR array where the mapping data will be
copied out after a successful mapping of \fIfd\fR.
.RE

.sp
.ne 2
.na
\fB\fIelements\fR\fR
.ad
.RS 12n
A pointer to the number of \fBmmapobj_result_t\fR elements pointed to by
\fIstorage\fR.  On return, \fIelements\fR contains the number of mappings
required to fully map the requested object.  If the original value of
\fIelements\fR is too small, \fBE2BIG\fR is returned and \fIelements\fR is
modified to contain the number of mappings necessary.
.RE

.sp
.ne 2
.na
\fB\fIarg\fR\fR
.ad
.RS 12n
A pointer to additional information that might be associated with the specific
request. Only the \fBMMOBJ_PADDING\fR request uses this argument. If
\fBMMOBJ_PADDING\fR is not specified, \fIarg\fR must be \fINULL\fR.
.RE

.SH DESCRIPTION
The \fBmmapobj()\fR function establishes a set of mappings between a process's
address space and a file.  By default, \fBmmapobj()\fR maps the whole file as a
single, private, read-only mapping.  The \fBMMOBJ_INTERPRET\fR flag instructs
\fBmmapobj()\fR to attempt to interpret the file and map the file according to
the rules for that file format.  The following \fBELF\fR and \fBAOUT\fR formats
are supported:
.sp
.ne 2
.na
\fB\fBET_EXEC\fR and \fBAOUT\fR executables\fR
.ad
.sp .6
.RS 4n
This format results in one or more mappings whose size, alignment and
protections are as described by the file's program header information. The
address of each mapping is explicitly defined by the file's program headers.
.RE

.sp
.ne 2
.na
\fB\fBET_DYN\fR and \fBAOUT\fR shared objects\fR
.ad
.sp .6
.RS 4n
This format results in one or more mappings whose size, alignment and
protections are as described by the file's program header information. The base
address of the initial mapping is chosen by \fBmmapobj()\fR. The addresses of
adjacent mappings are based off of this base address as defined by the file's
program headers.
.RE

.sp
.ne 2
.na
\fB\fBET_REL\fR and \fBET_CORE\fR\fR
.ad
.sp .6
.RS 4n
This format results in a single, read-only mapping that covers the whole file.
The base address of this mapping is chosen by \fBmmapobj()\fR.
.RE

.sp
.LP
The \fBmmapobj()\fR function will not map over any currently used mappings
within the process, except for the case of an \fBELF ET_EXEC\fR file for which
a previous reservation has been made via \fB/dev/null\fR. The most common way
to make such a reservation would be with an \fBmmap()\fR of \fB/dev/null\fR.
.sp
.LP
Mappings created with \fBmmapobj()\fR can be processed individually by other
system calls such as \fBmunmap\fR(2).
.sp
.LP
The \fBmmapobj_result\fR structure contains the following members:
.sp
.in +2
.nf
typedef struct mmapobj_result {
      caddr_t         mr_addr;         /* mapping address */
      size_t          mr_msize;        /* mapping size */
      size_t          mr_fsize;        /* file size */
      size_t          mr_offset;       /* offset into file */
      uint_t          mr_prot;         /* the protections provided */
      uint_t          mr_flags;        /* info on the mapping */
} mmapobj_result_t;
.fi
.in -2

.sp
.LP
The macro \fBMR_GET_TYPE\fR(\fImr_flags\fR) must be used when looking for the
above flags in the value of \fImr_flags\fR.
.sp
.LP
Values for \fImr_flags\fR include:
.sp
.in +2
.nf
MR_PADDING   0x1  /* this mapping represents requested padding */
MR_HDR_ELF   0x2  /* the ELF header is mapped at mr_addr */
MR_HDR_AOU   0x3  /* the AOUT header is mapped at mr_addr */
.fi
.in -2

.sp
.LP
When \fBMR_PADDING\fR is set, \fImr_fsize\fR and \fImr_offset\fR will both be
0.
.sp
.LP
The \fImr_fsize\fR member represents the amount of the file that is mapped into
memory with this mapping.
.sp
.LP
The \fImr_offset\fR member is the offset into the mapping where valid data
begins.
.sp
.LP
The \fImr_msize\fR member represents the size of the memory mapping starting at
\fImr_addr\fR. This size may include unused data prior to \fImr_offset\fR that
exists to satisfy the alignment requirements of this segment. This size may
also include any non-file data that are required to provide \fBNOBITS\fR data
(typically .\fBbss\fR). The system reserves the right to map more than
\fImr_msize\fR bytes of memory but only \fImr_msize\fR bytes will be available
to the caller of \fBmmapobj()\fR.
.SH RETURN VALUES
Upon successful completion, 0 is returned and \fIelements\fR contains the
number of program headers that are mapped for \fIfd\fR. The data describing
these elements are copied to storage such that the first \fIelements\fR members
of the storage array contain valid mapping data.
.sp
.LP
On failure, -1 is returned and \fBerrno\fR is set to indicate the error. No
data is copied to storage.
.SH ERRORS
The \fBmmapobj()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBE2BIG\fR\fR
.ad
.RS 14n
The \fIelements\fR argument was not large enough to hold the number of loadable
segments in \fIfd\fR. The \fIelements\fR argument will be modified to contain
the number of segments required.
.RE

.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 14n
The file system containing the \fIfd\fR to be mapped does not allow execute
access, or the file descriptor pointed to by \fIfd\fR is not open for reading.
.RE

.sp
.ne 2
.na
\fB\fBEADDRINUSE\fR\fR
.ad
.RS 14n
The mapping requirements overlap an object that is already used by the process.
.RE

.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 14n
There is insufficient room to reserve swap space for the mapping.
.sp
The file to be mapped is already locked using advisory or mandatory record
locking. See \fBfcntl\fR(2).
.RE

.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 14n
The \fIfd\fR argument is not a valid open file descriptor.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 14n
The \fIstorage\fR, \fIarg\fR, or \fIelements\fR argument points to an invalid
address.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 14n
The \fIflags\fR argument contains an invalid flag.
.sp
\fBMMOBJ_PADDING\fR was not specified in \fIflags\fR and \fIarg\fR was non-null.
.RE

.sp
.ne 2
.na
\fB\fBENODEV\fR\fR
.ad
.RS 14n
The \fIfd\fR argument refers to an object for which \fBmmapobj()\fR is
meaningless, such as a terminal.
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 14n
Insufficient memory is available to hold the program headers.
.sp
Insufficient memory is available in the address space to create the mapping.
.RE

.sp
.ne 2
.na
\fB\fBENOTSUP\fR\fR
.ad
.RS 14n
The current user data model does not match the \fIfd\fR to be interpreted;
thus, a 32-bit process that tried to use \fBmmapobj()\fR to interpret a 64-bit
object would return \fBENOTSUP\fR.
.sp
The \fIfd\fR argument is a file whose type can not be interpreted and
\fBMMOBJ_INTERPRET\fR was specified in \fIflags\fR.
.sp
The \fBELF\fR header contains an unaligned \fIe_phentsize\fR value.
.RE

.sp
.ne 2
.na
\fB\fBENOSYS\fR\fR
.ad
.RS 14n
An unsupported filesystem operation was attempted while trying to map in the
object.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Private
_
MT-Level	Async-Signal-Safe
.TE

.SH SEE ALSO
.BR ld.so.1 (1),
.BR fcntl (2),
.BR memcntl (2),
.BR mmap (2),
.BR mprotect (2),
.BR munmap (2),
.BR madvise (3C),
.BR mlockall (3C),
.BR msync (3C),
.BR elf (3ELF),
.BR a.out (5),
.BR attributes (7)
.sp
.LP
\fILinker and Libraries Guide\fR