Go to main content

man pages section 2: System Calls

Exit Print View

Updated: Thursday, June 13, 2019
 
 

mmapobj (2)

Name

mmapobj - map a file object

Synopsis

#include <sys/mman.h>

int mmapobj(int fd, uint_t flags, mmapobj_result_t *storage,
     uint_t *elements, void *arg);

Parameters

fd

The open file descriptor of the file to be mapped.

flags

Modify the default behavior of mmapobj(). The following flags are available.

MMOBJ_INTERPRET

Interpret the contents of the file descriptor instead of mapping the file as a single image. This flag can only be used with ELF files.

MMOBJ_PADDING

Add an additional mapping before the lowest mapping and after the highest mapping. The size of each of these padding areas is at least as large as the amount pointed to by arg. These padding areas are private to the process, do not reserve any swap space, and have no protections. To use these padding areas, the protections for the underlying mappings must be changed. See mprotect(2).

storage

A pointer to the mmapobj_result_t array where the mapping data is copied out after a successful mapping of fd.

elements

A pointer to the number of mmapobj_result_t elements pointed to by storage. On return, elements contains the number of storage elements that are required to describe the mappings of the requested object. If the value of elements is too small, E2BIG is returned and elements is modified to contain the number of storage elements necessary.

arg

A pointer to additional information that might be associated with the specific request. Only the MMOBJ_PADDING request uses this argument. If MMOBJ_PADDING is not specified, arg must be NULL.

Description

The mmapobj() function establishes a set of mappings between the address space of a process and the file provided by the descriptor fd. On return from mmapobj(), data describing the mapping of the file is copied out to the area defined by storage and elements.

By default, mmapobj() maps the whole file as a single, private, read-only mapping. In this case, only one storage element is required to describe the mapped file.

The MMOBJ_INTERPRET flag instructs mmapobj() to attempt to interpret the file and map the file according to the rules for that file format. ELF objects define their mapping requirements in terms of segments. Typically, such objects define a text and data segment, as defined by the file's program header information. These segments are created from mappings of the file, and can be augmented with mappings that provide zero-filled memory. In this typical case, two storage elements are required to describe the segments of the mapped file.

The following ELF formats are supported.

ET_EXEC executables

This format results in the file being mapped into one or more segments whose size, alignment and protections are as described by the file's program header information. The address of each segment is explicitly defined by the file's program headers.

ET_DYN shared objects

This format results in the file being mapped into one or more segments whose size, alignment and protections are as described by the file's program header information. The base address of the initial segment is chosen by mmapobj(). The addresses of adjacent segments are based off of this base address as defined by the file's program headers.

ET_REL and ET_CORE

This format results in a single, read-only mapping that covers the whole file. The base address of this mapping is chosen by mmapobj().

The mmapobj() function will not map over any currently used mappings within the process, except for the case of an ELF ET_EXEC file for which a previous reservation has been made via /dev/null. The most common way to make such a reservation is an mmap() of /dev/null.

Mappings created with mmapobj() can be processed individually by other system calls such as munmap(2).

The mmapobj_result structure contains the following members.

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 mapping */
      uint_t      mr_prot;     /* protections provided */
      uint_t      mr_flags;    /* info on the mapping */
} mmapobj_result_t;

The MR_GET_TYPE() macro must be used to interpret any mr_flags. The following mr_flags are available.

MR_PADDING   0x1  /* mapping provides padding */
MR_HDR_ELF   0x2  /* ELF header is mapped at mr_addr */

When MR_PADDING is set, mr_fsize and mr_offset are both 0.

The mr_fsize member represents the amount of the file that is mapped into memory with this mapping.

The mr_offset member is the offset into the mapping where valid data begins.

The mr_msize member represents the size of the memory mapping starting at mr_addr. This size may include unused data prior to mr_offset. This data can exist to satisfy the alignment requirements of segments within an interpreted ELF file. This size may also include any non-file data that is required to provide zero-filled, or NOBITS data (typically .bss). The system reserves the right to map more than mr_msize bytes of memory but only mr_msize bytes is available to the caller of mmapobj().

Return Values

Upon successful completion, 0 is returned and elements contains the number of valid entries in the storage array that are required to describe the mapping for fd. The data describing these elements are copied to storage such that the first elements members of the storage array contain valid mapping data.

On failure, -1 is returned and errno is set to indicate the error. No data is copied to storage, however, elements can be updated in some error cases.

Errors

The mmapobj() function will fail if:

E2BIG

The elements argument is not large enough to describe the number of mappings for fd. The elements argument is modified to contain the number of mappings required.

EACCES

The file system containing the fd to be mapped does not allow execute access, or the file descriptor pointed to by fd is not open for reading.

EADDRINUSE

The mapping requirements overlap an object that is already used by the process.

EAGAIN

There is insufficient room to reserve swap space for the mapping.

The file to be mapped is already locked using advisory or mandatory record locking. See fcntl(2).

EBADF

The fd argument is not a valid open file descriptor.

EFAULT

The storage, arg, or elements argument points to an invalid address.

EINVAL

The flags argument contains an invalid flag.

The flags argument does not contain MMOBJ_PADDING and arg is non-null.

The file to be mapped has a length of 0.

ENODEV

The fd argument refers to an object for which mmapobj() is meaningless, such as a terminal.

ENOMEM

Insufficient memory is available in the address space to create the mapping.

The flags argument contains MMOBJ_INTERPRET and there is insufficient memory available to hold the program headers for the ELF file.

ENOTSUP

The current user data model does not match the fd to be interpreted. For example, a 32-bit process that tried to use mmapobj() to interpret a 64-bit object would return ENOTSUP.

The flags argument contains MMOBJ_INTERPRET and the fd argument is a file whose type can not be interpreted.

The ELF header contains an unaligned e_phentsize value.

ENOSYS

An unsupported file system operation is attempted while trying to map in the object.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Private
MT-Level
Async-Signal-Safe

See Also

ld.so.1(1), fcntl(2), memcntl(2), mmap(2), mprotect(2), munmap(2), madvise(3C), mlockall(3C), msync(3C), elf(3ELF), a.out(5), attributes(7)

Oracle Solaris 11.4 Linkers and Libraries Guide