Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

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: https://gnats.NetBSD.org/55177 for details.

NetBSD 10.99                      May 2, 2018                     NetBSD 10.99