*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> free (3)              



NAME    [Toc]    [Back]

     malloc, calloc, realloc, free, cfree - memory allocation and

SYNOPSIS    [Toc]    [Back]

     #include <stdlib.h>

     void *
     malloc(size_t size);

     void *
     calloc(size_t nmemb, size_t size);

     void *
     realloc(void *ptr, size_t size);

     free(void *ptr);

     cfree(void *ptr);

     char * malloc_options;

DESCRIPTION    [Toc]    [Back]

     The  malloc()  function allocates uninitialized space for an
object whose
     size is specified by size.  The malloc() function  maintains
     lists  of  free  blocks  according to size, allocating space
from the appropriate

     The allocated space  is  suitably  aligned  (after  possible
pointer coercion)
     for  storage  of  any  type  of  object.  If the space is of
pagesize or larger,
 the memory returned will be page-aligned.

     Allocation of a zero size object returns a pointer to a zero
size object.
     This  zero size object is access protected, so any access to
it will generate
 an exception (SIGSEGV).  Many zero-sized  objects  can
be placed consecutively
  in  shared protected pages.  The minimum size of
the protection
     on each object is suitably aligned and sized  as  previously
stated, but
     the  protection  may  extend further depending on where in a
protected zone
     the object lands.

     The calloc() function allocates space for an array of  nmemb
objects, each
     of whose size is size.  The space is initialized to all bits

     The free() function causes the space pointed to by ptr to be
     that is, at least made available for further allocation, but
if possible,
     it will passed back to the kernel with sbrk(2).  If ptr is a
null pointer,
 no action occurs.

     A  cfree()  function is also provided for compatibility with
old systems
     and other malloc  libraries;  it  is  simply  an  alias  for

     The realloc() function changes the size of the object pointed to by ptr
     to size bytes and returns a pointer to the (possibly  moved)
object.  The
     contents of the object are unchanged up to the lesser of the
new and old
     sizes.  If the new size is larger, the value  of  the  newly
allocated portion
  of  the object is indeterminate and uninitialized.  If
ptr is a null
     pointer, the realloc() function behaves  like  the  malloc()
function for
     the  specified  size.  If the space cannot be allocated, the
object pointed
     to by ptr is unchanged.  If size is zero and ptr  is  not  a
null pointer,
     the  object it points to is freed and a new zero size object
is returned.

     When using realloc() one must be careful to avoid  the  following idiom:

           size += 50;
           if ((p = realloc(p, size)) == NULL)
                   return (NULL);

     Do  not  adjust  the variable describing how much memory has
been allocated
     until one knows the allocation has  been  successful.   This
can cause aberrant
  program  behavior if the incorrect size value is used.
In most cases,
 the above sample will also result in a leak  of  memory.
As stated
     earlier,  a  return value of NULL indicates that the old object still remains
 allocated.  Better code looks like this:

           newsize = size + 50;
           if ((newp = realloc(p, newsize)) == NULL) {
                   p = NULL;
                   size = 0;
                   return (NULL);
           p = newp;
           size = newsize;

     Malloc  will  first  look  for  a   symbolic   link   called
/etc/malloc.conf and
     next  check the environment for a variable called MALLOC_OPTIONS and finally
 for the global variable malloc_options and  scan  them
for flags in
     that  order.   Flags are single letters, uppercase means on,
     means off.

     A       ``Abort''.   malloc()  will  coredump  the  process,
rather than tolerate
  failure.  This is a very handy debugging aid,
since the
             core file will represent the time of failure, rather
than when
             the null pointer was accessed.

     D        ``Dump''.   malloc() will dump statistics in a file
             malloc.out at exit.  This option  requires  the  library to have
             been  compiled  with -DMALLOC_STATS in order to have
any effect.

     F       ``Freeguard''.  Enable use  after  free  protection.
Unused pages
             on  the  freelist  are  read  and write protected to
cause a segmentation
 fault upon access.

     G       ``Guard''.  Enable guard pages and chunk  randomization.  Each
             page  size  or  larger  allocation  is followed by a
guard page that
             will cause a segmentation  fault  upon  any  access.
Smaller than
             page size chunks are returned in a random order.

     H        ``Hint''.  Pass a hint to the kernel about pages we
don't use.
             If the machine is paging a lot this may help a  bit.

     J        ``Junk''.   Fill some junk into the area allocated.
             junk is bytes of 0xd0; this is  pronounced  ``Duh''.

     N        Do  not  output  warning messages when encountering
possible corruption
 or bad pointers.

     R       ``realloc''.  Always reallocate  when  realloc()  is
called, even if
             the  initial  allocation  was  big enough.  This can
             aid in compacting memory.

     X       ``xmalloc''.  Rather than return  failure,  abort(3)
the program
             with  a diagnostic message on stderr.  It is the intention that
             this option be set at compile time by  including  in
the source:

                   extern char *malloc_options;
                   malloc_options = "X";

     Z        ``Zero''.   Fill  some junk into the area allocated
(see J), except
             for the exact length the user asked  for,  which  is

     <        ``Half  the  cache  size''.  Reduce the size of the
cache by a factor
 of two.

     >       ``Double the cache size''.  Double the size  of  the
cache by a
             factor of two.

     So to set a systemwide reduction of cache size and coredumps
on problems
     one would: ln -s 'A<' /etc/malloc.conf

     The J and Z flags are mostly for testing and debugging.   If
a program
     changes  behavior if either of these options are used, it is

     The default cache size is 16 pages.

RETURN VALUES    [Toc]    [Back]

     The malloc() and calloc() functions return a pointer to  the
     space  if  successful; otherwise, a null pointer is returned
and errno is
     set to ENOMEM.

     The free() and cfree() functions return no value.

     The realloc() function returns a pointer  to  the  (possibly
moved) allocated
  space  if  successful;  otherwise, a null pointer is returned and errno
     is set to ENOMEM.

ENVIRONMENT    [Toc]    [Back]

     See above.

FILES    [Toc]    [Back]

     /etc/malloc.conf  symbolic link to filename  containing  option flags

DIAGNOSTICS    [Toc]    [Back]

     If  malloc(), calloc(), realloc(), or free() detect an error
or warning
     condition, a message will be printed to  file  descriptor  2
(not using
     stdio).   Errors  will  always  result  in the process being
abort(3)'ed.  If
     the A option has been specified, warnings will also abort(3)
the process.

     Here  is  a brief description of the error messages and what
they mean:

     ``(ES): mumble mumble mumble''
                 malloc() has been compiled  with  -DEXTRA_SANITY
and something
                 looks  fishy  in  there.  Consult sources and/or

     ``allocation failed''
                 If the A option is specified it is an error  for
                 calloc(), or realloc() to return NULL.

     ``mmap(2) failed, check limits.''
                 This  is  a  rather weird condition that is most
likely to indicate
 a seriously overloaded system  or  a  ulimit(1) restriction.

     ``freelist is destroyed.''
                 malloc()'s  internal  freelist  has been stomped

     Here is a brief description of the warning messages and what
they mean:

     ``chunk/page is already free.''
                 There  was  an  attempt to free a chunk that had
already been

     ``junk pointer, too high to make sense.''
                 The pointer doesn't make sense.  It's above  the
area of memory
  that  malloc()  knows something about.  This
could be a
                 pointer from some mmap(2)'ed memory.

     ``junk pointer, too low to make sense.''
                 The pointer doesn't make sense.  It's below  the
area of memory
  that  malloc()  knows something about.  This
pointer probably
 came from your data or bss segments.

     ``malloc() has never been called.''
                 Nothing has ever been allocated,  yet  something
is being freed
                 or realloc'ed.

     ``modified (chunk-/page-) pointer.''
                 The  pointer  passed to free or realloc has been

     ``pointer to wrong page.''
                 The pointer that malloc() is trying to  free  is
not pointing
                 to a sensible page.

     ``recursive call.''
                 An  attempt  was  made  to call recursively into
these functions,
                 i.e., from a signal handler.  This  behavior  is
not supported.
                 In  particular,  signal  handlers should not use
any of the
                 malloc() functions nor utilize any  other  functions which may
                 call malloc() (e.g., stdio(3) routines).

     ``unknown char in MALLOC_OPTIONS''
                 We found something we didn't understand.

SEE ALSO    [Toc]    [Back]

     brk(2), alloca(3), getpagesize(3)

STANDARDS    [Toc]    [Back]

     The  malloc()  function conforms to ANSI X3.159-1989 (``ANSI

HISTORY    [Toc]    [Back]

     The present implementation of  malloc()  started  out  as  a
filesystem on a
     drum  attached  to a 20-bit binary challenged computer built
with discrete
     germanium transistors, and it has since graduated to  handle
primary storage
 rather than secondary.

     The  main difference from other malloc() implementations are
believed to
     be that the free pages are  not  accessed  until  allocated.
Most malloc()
     implementations  will  store  a data structure containing a,
possibly double-,
 linked list in the free chunks of memory, used to  tie
all the free
     memory  together.   That  is a quite suboptimal thing to do.
Every time the
     free-list is traversed, all the otherwise unused,  and  very
likely paged
     out, pages get faulted into primary memory, just to see what
lies after
     them in the list.

     On systems which are paging, this  can  increase  the  pagefaults of a process
 by a factor of five.

OpenBSD      3.6                          August     27,     1996
[ Back ]
 Similar pages
Name OS Title
memcluster FreeBSD memory allocation/deallocation system
memget FreeBSD memory allocation/deallocation system
memput FreeBSD memory allocation/deallocation system
memstats FreeBSD memory allocation/deallocation system
memory FreeBSD general memory allocation operations
malloc_cv IRIX WorkShop memory allocation library
valloc NetBSD aligned memory allocation function
memory NetBSD general memory allocation operations
valloc FreeBSD aligned memory allocation function
memory IRIX Validated memory allocation interface.
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service