mmap(2)                                                         mmap(2)

  mmap()

  NAME

    mmap() - map a file into memory

  SYNOPSIS

    #include 

    void *mmap(void *addr, size_t len, int prot,
               int flags, int fd, off_t off);

  DESCRIPTION

    The mmap(2) function maps a file on disk into a buffer in memory so that
    when bytes are retrieved from the buffer, they're read from the file. The
    file has the open file descriptor fd and the function maps len bytes of
    the file. The portion of the file to be mapped to the buffer is off bytes
    from the beginning of the file. The function returns a pointer (pa such
    that the range [pa pa+ len) is the same as the range [fd fd+ len).

    addr
        The point in the address space where the mapping should be placed.
        Normally this is set to zero, which indicates that the system may
        place the mapping anywhere. If it's a positive non-zero value, then it
        is considered a hint to the system for placing the buffer. This can be
        changed by setting MAP_FIXED in the flags argument; if set, the
        function must return the value of addr as the address of the buffer.
        If it cannot, the function fails. The value of addr should be a
        multiple of the system's virtual memory page size, returned by
        sysconf(2) with the argument _SC_PAGESIZE (or _SC_PAGE_SIZE).

    len
        The length of the mapped space, in bytes. It's rounded up to the
        nearest multiple of sysconf(_SC_PAGE_SIZE).

    prot
        The set of accesses permitted to the pages being mapped. Traditionally
        these should be the same as the open mode of the file (that is, you
        can't write to the memory if the file was opened read-only). These
        access values are defined in :

        PROT_READ
            Read permission.

        PROT_WRITE
            Write permission.

        PROT_EXEC
            Execute permission.

        PROT_NONE
            No access allowed.

    flags
        Other information about how the mapped file is to be handled. Possible
        values are:

        MAP_SHARED
            Changes can be shared; cannot be specified with MAP_PRIVATE. When
            the calling process writes to the memory region, the file may be
            changed. These changes are visible in all MAP_SHARED mappings of
            the same portion of the file, by any process.

        MAP_PRIVATE
            Changes are private; cannot be specified with MAP_SHARED. When the
            calling process writes to the memory region, the file isn't
            changed, they affect a copy of the file. No other process mapping
            the same portion of the file can see these changes.

        MAP_FIXED
            The pointer returned by the function must be equal to addr.
            Normally, the returned pointer is derived from the addr but
            doesn't have to be identical. This is the least portable way of
            coding with the function.
        This information is retained across a fork(2), but not across an
        exec(2).

    fd
        The file descriptor of the file to be mapped. The file should have
        already been opened.

    off
        The offset to the part of the file where mapping should start. The
        value of off should be a multiple of the system's virtual memory page
        size, returned by sysconf(_SC_PAGESIZE).

    When the process terminates, the mapped region is unmapped. It does not
    unmap when fd is closed.

    You can also explicitly unmap the region by calling the munmap(2)
    function.

  RETURN VALUE

    On success, mmap(2) returns the address where the mapping was placed. On
    failure, it returns MAP_FAILURE and sets errno to indicate the error.

  ERRORS

    The mmap(2) function can fail if:

    [EBADF]
        The file descriptor fd was not valid.

    [EACCES]
        The file indicated by fd wasn't open to be read; or fd wasn't open for
        writing and PROT_WRITE was specified for a MAP_SHARED mapping.

    [ENXIO]
        The addresses [off, off+len) were invalid for fd.

    [EINVAL]
        The off (or the addr argument, if MAP_FIXED was specified), was not a
        multiple of the page size (as returned by sysconf(2)) or was otherwise
        invalid; or flags was invalid (neither MAP_PRIVATE nor MAP_SHARED was
        set).

    [EINVAL]
        MAP_ANON was specified and the off address was non-zero; the size of
        the anonymous memory section created is len bytes long.

    [EMFILE]
        Fulfilling the request would exceed the system limit on the number of
        mapped regions.

    [ENODEV]
        The fd refers to a file of an unsupported type.

    [ENOMEM]
        If MAP_FIXED was specified, then the range [addr, addr+len) is greater
        than allowed for a process' address space; if MAP_FIXED was not
        specified, there is insufficient room in the address space to perform
        the mapping.

  SEE ALSO

    exec(2)

    fcntl(2)

    fork(2)

    munmap(2)

    shmat(2)

    sysconf(2)

  USAGE NOTES

    The mmap function is thread safe.

    The mmap function is not async-signal safe.