mremap(2) - NetBSD Manual Pages

MREMAP(2)                 NetBSD 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 bound-
                        ary, i.e. ensure that the lowest n bits of the address
                        are zero.  The parameter n should be the base 2 loga-
                        rithm 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 plat-
                        form'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, fac-
                        toring 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 occu-
                        pied, 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