mmap()

map a region of a memory object

Synopsis:

#include <sys/mman.h>
void *mmap( void *addr, size_t len,
            int prot, int flags, 
            int fildes, off_t off );

Description:

The mmap() function maps a region of the "memory object" specified by fildes into the calling process' address space. (The fildes was obtained by a previous call to the shm_open() function).

A region within the memory object beginning at offset off and continuing for len bytes is mapped into the caller's address space at the location returned by the mmap() function.

The offset off must be on a 4K page boundary.

The addr parameter is an address in the caller's space where the mmap() function is to attempt to place the mapping. The only portable value for addr is zero, which lets the operating system determine the address of the mapping.

The prot parameter specifies the access capabilities to the memory region being mapped. The bits that can be combined in this field are defined in <sys/mman.h>, and are described in the section on that file in the Header Files chapter.

The flags parameter specifies further information about the handling of the mapped region. At least the following flag bits may be combined, as defined in <sys/mman.h>:

MAP_FIXED: Interpret addr exactly.
MAP_PRIVATE: Changes are private.
MAP_SHARED: Share changes.

Returns:

The address of the mapped memory region within the caller's space. On error, -1 is returned, and errno is set.

Errors:

EACCES: The fildes isn't open for the correct mode.
EAGAIN: The mapping couldn't be locked in memory, due to a lack of resources.
EBADF: The fildes is invalid.
EINVAL: One of the arguments, addr, flag or prot is invalid.
ENODEV: The fildes argument refers to an object for which mmap() is meaningless, such as a terminal.
ENOMEM: The mapping couldn't be locked in memory because it would require more space than the system is able to supply.
ENOSYS: The function mmap() isn't supported by this implementation.
ENOTSUP: MAP_FIXED or MAP_PRIVATE was specified in the flags argument, and the implementation doesn't support this functionality.
This implementation doesn't support the combination of accesses requested in the prot argument.
ENXIO: The len or off argument is invalid for this fildes.

Classification:

POSIX 1003.4

Safety:
Interrupt handler	No
Signal handler	Yes
Thread	Yes