mmap(2)
Name
mmap − maps memory of a character device
Syntax
#include <sys/types.h>
#include <sys/mman.h>
caddr_t mmap(addr, len, prot, flags, fd, off)
caddr_t addr;
size_t len;
int prot;
int flags;
int fd;
off_t off;
Arguments
addr Specifies the address space of the calling process where mmap begins mapping the memory associated with the specified character device.
len Specifies the number of bytes to map.
prot Specifies the protection flag for the mapping. The protection flag is the bitwise inclusive OR of these valid protection flag bits defined in mman.h: PROT_READ or PROT_WRITE.
flags Specifies the mapping flag. The mapping flag is the bitwise inclusive OR of these valid flag mapping bits defined in mman.h: MAP_SHARED or MAP_FIXED.
fd Specifies the file descriptor for the character device being mapped.
off Specifies the offset in bytes into the character device’s memory.
Description
The mmap system call maps the memory of a character device (fd) starting at a specified offset (off) for a specified number of bytes (len) into the address space of the calling process. The mmap routine does not map into private data, stack, or text segments. This routine does not replace any existing mappings. All the mapped regions are inherited by a child process on a fork.
When calling mmap, you need to:
•Align the offset
You must align the offset (off) on a page boundary as returned by the getpagesize system call.
•Indicate the number of bytes to map
The number of bytes to map (len) need not be a multiple of the page size as returned by getpagesize. However, mmap will round the value of len to the nearest multiple of the page size as returned by getpagesize and perform the mapping over whole pages.
•Specify the protection for the mapping
You specify the protection for the mapping by ORing the prot argument with one or more of the constants PROT_READ or PROT_WRITE. If you specify only PROT_READ, both VAX and RISC architectures will grant read access. If you specify only PROT_WRITE, then both VAX and RISC architectures will grant read and write access.
•Indicate the address at which the mapping occurs
The addr and flags arguments are used by mmap to determine the actual address at which the mapping is done. You specify the mapping flag by ORing the flags argument with one or more of the constants MAP_FIXED or MAP_SHARED.
Based on the values you specify for addr and flags, mmap performs the mapping as follows:
-If addr is equal to zero, mmap selects the address at which the mapping is done.
-If addr is not equal to zero and you specified MAP_FIXED, the mapping is done at the address specified in addr. You can obtain the boundary on which addr must be aligned by calling the getsysinfo system call.
-If addr is not equal to zero and you did not specify MAP_FIXED, the mapping is done at the address rounded down to the boundary returned by getsysinfo. The value returned by getsysinfo is machine-dependent.
Restrictions
You must observe the following restrictions when calling mmap:
•Maximum number of mapped regions for each process
The shared memory functionality upon which mmap is implemented requires that you not exceed the maximum number of shared memory segments allowed for each process. The default value is six shared memory segments for each process. You can configure (in the system configuration file) the number of shared memory segments for each process by using the constant SMSEG.
•Maximum number of mapped regions on the system
The shared memory functionality imposes a limit on the maximum number of mapped regions on the system. The default limit is 100, sufficient to support a maximum configuration of all devices that can be mapped. The maximum configuration is 2*21 devices (2 VME adapters, 21 devices for each bus).
•A process mapping the same region of device memory
A process cannot map the same region of device memory more than once into its address space. This limitation is a result of the lack of multiple attach capability for shared memory. However, a single process can map different regions of device memory simultaneously into its address space. Two regions of memory are identical only if they start at the same offset in device memory and are of the same length.
•Use of the mprotect() system call
The mprotect system call does not work on the addresses mapped by a call to mmap. The reason is that mprotect does not work for shared memory and therefore cannot be used to change protection for the address space mapped by mmap.
Return Value
If successful, mmap returns the address where the mapping was done. Otherwise, it returns −1 and sets the errno argument to one of the errors listed in the Diagnostics section.
Diagnostics
The call to mmap fails if one or more of the following is true:
[EBADF] The device, represented by the file descriptor fd, is not open.
[EACCES]
The device, represented by the file descriptor fd, is not open for read operations and you specified the protection flag PROT_READ in prot. Or, the device is not open for write operations and you specified the protection flag PROT_WRITE in prot.
[ENXIO] Addresses in the range [ off, off + len ] are invalid for this device, represented by the file descriptor fd.
[EINVAL] You did not specify either MAP_SHARED or MAP_FIXED in the flags argument.
[EINVAL] You did not specify either PROT_READ or PROT_WRITE in the prot argument.
[EINVAL] The file descriptor, fd, is not a valid file descriptor for a character device.
[ENODEV]
The file descriptor, fd, refers to a device that does not support the mmap system call.
[ENOMEM]
There is not enough room in the address space to perform the mapping.