MREMAP(2)

MREMAP(2) | System Calls Manual | MREMAP(2)

# NAME

`mremap` — re-map a virtual memory address

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <sys/mman.h>`

void *
`mremap`(void *oldp, size_t oldsize, void *newp, size_t newsize, int flags);

# DESCRIPTION

The `mremap`() function resizes the mapped range (see mmap(2)) starting at oldp and having size oldsize to newsize. The following arguments can be `OR`'ed together in the flags argument:

`MAP_ALIGNED`(n)
  The allocation should be aligned to the given boundary, i.e. ensure that the lowest n bits of the address are zero. The parameter n should be the base 2 logarithm of the desired alignment (e.g., to request alignment to 16K, use 14 as the value for n). The alignment must be equal to or greater than the platform's page size as returned by sysconf(3) with the `_SC_PAGESIZE` request.
`MAP_FIXED`
  newp is tried and `mremap`() fails if that address can't be used as new base address for the range. Otherwise, oldp and newp are used as hints for the position, factoring in the given alignment.
`MAP_REMAPDUP`
  Duplicate the mapping. Both address ranges reference the same pages, but can have different protection flags.

# RETURN VALUES

`mremap`() returns the new address or `MAP_FAILED`, if the remap failed.

# EXAMPLES

The following example program creates a two mappings for the same memory range, one RW- and one R-X.

    #include <sys/types.h>
    #include <sys/mman.h>

    #include <stdio.h>
    #include <string.h>
    #include <unistd.h>
    #include <stdlib.h>
    #include <err.h>

    static int
    return_1(void)
    {
    	return 1;
    }

    static void
    return_1_end(void)
    {
    }

    static int
    return_2(void)
    {
    	return 2;
    }

    static void
    return_2_end(void)
    {
    }

    int
    main(int argc, char *argv[])
    {
            void *maprw, *maprx;
    	int rv;
    	size_t page = (size_t)sysconf(_SC_PAGESIZE);

    	// Create the first mapping that has no protections, but intended
    	// protections only
    	maprw = mmap(NULL, page,
    	    PROT_MPROTECT(PROT_EXEC|PROT_WRITE|PROT_READ),
                MAP_ANON|MAP_PRIVATE, -1, 0);
    	if (maprw == MAP_FAILED)
    		err(EXIT_FAILURE, "mmap failed");

            // Create the second mapping for the same physical space, which
    	// again has no protections.
    	maprx = mremap(maprw, page, NULL, page, MAP_REMAPDUP);
    	if (maprx == MAP_FAILED)
    		err(EXIT_FAILURE, "mremap failed");

    	// Set the first mapping read/write
            if (mprotect(maprw, page, PROT_READ|PROT_WRITE) == -1)
    		err(EXIT_FAILURE, "mprotect(rw) failed");

    	// Set the second mapping read/execute
            if (mprotect(maprx, page, PROT_READ|PROT_EXEC) == -1)
    		err(EXIT_FAILURE, "mprotect(rx) failed");

    #define XS(a) (size_t)((uintptr_t)(a ## _end) - (uintptr_t)(a))

    	// Copy and run the first function
    	memcpy(maprw, return_1, XS(return_1));
    	__builtin___clear_cache(maprw, (void *)((uintptr_t)maprw + page));
    	rv = ((int (*)(void))maprx)();
    	printf("%d\n", rv);

    	// Copy and run the second function
    	memcpy(maprw, return_2, XS(return_2));
    	__builtin___clear_cache(maprw, (void *)((uintptr_t)maprw + page));
    	rv = ((int (*)(void))maprx)();
    	printf("%d\n", rv);

    	return EXIT_SUCCESS;
    }

# COMPATIBILITY

The semantics of `mremap`() differ from the one provided by glibc on Linux in that the newp argument was added and a different set of flags are implemented.

# ERRORS

The `mremap`() function fails if:

[`E2BIG`]
  A request to extend oldp failed because of address overflow.
[`EINVAL`]
  If oldp or newp are not page aligned, or oldsize or newsize are not a multiple of the page size, or if oldp + oldsize or newp + newsize wrap around, or if an invalid alignment was requested in the flags argument, or if the request was to extend oldp and the extension address space either did not fit, was already occupied, or had set permissions.
[`ENOENT`]
  If the oldp segmented was not already mapped.
[`ENOMEM`]
  If there was either no space to allocate/move memory, or if a fixed allocation was requested in the flags that could not be accommodated.

# SEE ALSO

mmap(2), munmap(2)

# HISTORY

The `mremap`() system call appeared in NetBSD 5.0. It was based on the code that supports `mremap`() compatibility for Linux binaries.

# BUGS

If a mapping is created by mmap(2) with `MAP_PRIVATE` and then duplicated by `mremap` with `MAP_REMAPDUP`, calling fork(2) destroys the coupling between the original and duplicate mapping. Workarounds:

- Create the original mapping with `MAP_SHARED`.
- Use minherit(2) with `MAP_INHERIT_NONE` on the writable mapping.
- Don't use fork(2); use posix_spawn(2).

See PR lib/55177 for details.

May 2, 2018 | NetBSD 11.0