'\" 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 \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(5) 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 \fBld.so.1\fR(1), \fBfcntl\fR(2), \fBmemcntl\fR(2), \fBmmap\fR(2), \fBmprotect\fR(2), \fBmunmap\fR(2), \fBelf\fR(3ELF), \fBmadvise\fR(3C), \fBmlockall\fR(3C), \fBmsync\fR(3C), \fBa.out\fR(4), \fBattributes\fR(5) .sp .LP \fILinker and Libraries Guide\fR