mremap

MREMAP(2)		  Linux Programmer’s Manual		    MREMAP(2)



NAME
       mremap - re-map a virtual memory address

SYNOPSIS
       #include <unistd.h>
       #include <sys/mman.h>

       void  *	mremap(void  *old_address, size_t old_size , size_t new_size,
       unsigned long flags);

DESCRIPTION
       mremap expands (or shrinks) an existing	memory	mapping,  potentially
       moving  it  at the same time (controlled by the flags argument and the
       available virtual address space).

       old_address is the old address of the virtual memory  block  that  you
       want  to	 expand	 (or  shrink).	 Note that old_address has to be page
       aligned. old_size is  the  old  size  of	 the  virtual  memory  block.
       new_size	 is  the requested size of the virtual memory block after the
       resize.

       The flags argument is a bitmap of flags.

       In Linux the memory is divided into pages.  A user  process  has	 (one
       or)  several linear virtual memory segments.  Each virtual memory seg-
       ment has one or more mappings to real memory pages (in  the  page  ta-
       ble).   Each  virtual  memory  segment  has its own protection (access
       rights), which may cause a segmentation violation  if  the  memory  is
       accessed	 incorrectly (e.g., writing to a read-only segment).  Access-
       ing virtual memory outside of the segments will also cause a segmenta-
       tion violation.

       mremap  uses  the Linux page table scheme.  mremap changes the mapping
       between virtual addresses and memory  pages.   This  can	 be  used  to
       implement a very efficient realloc.


FLAGS
       MREMAP_MAYMOVE
	      indicates	 if  the operation should fail, or change the virtual
	      address if the resize cannot be done  at	the  current  virtual
	      address.


RETURN VALUE
       On  success  mremap  returns a pointer to the new virtual memory area.
       On error, the value MAP_FAILED (that is, (void *) -1) is returned, and
       errno is set appropriately.


ERRORS
       EINVAL An  invalid argument was given. Most likely old_address was not
	      page aligned.

       EFAULT "Segmentation fault." Some address in the range old_address  to
	      old_address+old_size  is	an invalid virtual memory address for
	      this process.  You can also get EFAULT even if there exist map-
	      pings  that  cover the whole address space requested, but those
	      mappings are of different types.

       EAGAIN The memory segment is locked and cannot be re-mapped.

       ENOMEM The memory area cannot  be  expanded  at	the  current  virtual
	      address,	and the MREMAP_MAYMOVE flag is not set in flags.  Or,
	      there is not enough (virtual) memory available.

NOTES
       With current glibc  includes,  in  order	 to  get  the  definition  of
       MREMAP_MAYMOVE,	you  need  to  define  _GNU_SOURCE  before  including
       <sys/mman.h>.

CONFORMING TO
       This call is Linux-specific,  and  should  not  be  used	 in  programs
       intended	 to  be	 portable.  4.2BSD had a (never actually implemented)
       mremap(2) call with completely different semantics.

SEE ALSO
       getpagesize(2), realloc(3), malloc(3), brk(2), sbrk(2), mmap(2)

       Your favorite OS text book  for	more  information  on  paged  memory.
       (Modern	Operating  Systems  by	Andrew S. Tannenbaum, Inside Linux by
       Randolf Bentson, The Design of the UNIX Operating System by Maurice J.
       Bach.)




Linux 1.3.87			  1996-04-12			    MREMAP(2)