Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MALLOC(3)		   Linux Programmer's Manual		     MALLOC(3)

       calloc, malloc, free, realloc - Allocate	and free dynamic memory

       #include	<stdlib.h>

       void *calloc(size_t nmemb, size_t size);
       void *malloc(size_t size);
       void free(void *ptr);
       void *realloc(void *ptr,	size_t size);

       calloc()	 allocates memory for an array of nmemb	elements of size bytes
       each and	returns	a pointer to the allocated memory.  The	memory is  set
       to  zero.  If nmemb or size is 0, then calloc() returns either NULL, or
       a unique	pointer	value that can later be	successfully passed to free().

       malloc()	 allocates  size  bytes	and returns a pointer to the allocated
       memory.	The memory is not  cleared.   If  size	is  0,	then  malloc()
       returns	either	NULL, or a unique pointer value	that can later be suc-
       cessfully passed	to free().

       free() frees the	memory space pointed to	by ptr,	which must  have  been
       returned	by a previous call to malloc(),	calloc() or realloc().	Other-
       wise, or	if free(ptr) has already been called before, undefined	behav-
       ior occurs.  If ptr is NULL, no operation is performed.

       realloc()  changes  the	size  of the memory block pointed to by	ptr to
       size bytes.  The	contents will be unchanged to the minimum of  the  old
       and new sizes; newly allocated memory will be uninitialized.  If	ptr is
       NULL, then the call is equivalent to malloc(size), for  all  values  of
       size;  if  size is equal	to zero, and ptr is not	NULL, then the call is
       equivalent to free(ptr).	  Unless  ptr  is  NULL,  it  must  have  been
       returned	by an earlier call to malloc(),	calloc() or realloc().	If the
       area pointed to was moved, a free(ptr) is done.

       For calloc() and	malloc(), return a pointer to  the  allocated  memory,
       which  is  suitably  aligned for	any kind of variable.  On error, these
       functions return	NULL.  NULL may	also be	returned by a successful  call
       to  malloc()  with  a size of zero, or by a successful call to calloc()
       with nmemb or size equal	to zero.

       free() returns no value.

       realloc() returns a pointer to the newly	 allocated  memory,  which  is
       suitably	 aligned  for  any  kind of variable and may be	different from
       ptr, or NULL if the request fails.  If size was equal to	0, either NULL
       or a pointer suitable to	be passed to free() is returned.  If realloc()
       fails the original block	is left	untouched; it is not freed or moved.

       C89, C99.

       Normally, malloc() allocates memory from	the heap, and adjusts the size
       of the heap as required,	using sbrk(2).	When allocating	blocks of mem-
       ory larger than MMAP_THRESHOLD bytes, the glibc malloc()	implementation
       allocates  the  memory  as  a  private anonymous	mapping	using mmap(2).
       MMAP_THRESHOLD is 128 kB	by  default,  but  is  adjustable  using  mal-
       lopt(3).	  Allocations  performed  using	 mmap(2) are unaffected	by the
       RLIMIT_DATA resource limit (see getrlimit(2)).

       The Unix98 standard requires malloc(), calloc(),	and realloc()  to  set
       errno to	ENOMEM upon failure.  Glibc assumes that this is done (and the
       glibc versions of these routines	do this); if you use a private	malloc
       implementation  that  does not set errno, then certain library routines
       may fail	without	having a reason	in errno.

       Crashes in malloc(), calloc(), realloc(), or free() are	almost	always
       related	to  heap corruption, such as overflowing an allocated chunk or
       freeing the same	pointer	twice.

       Recent versions of Linux	libc  (later  than  5.4.23)  and  glibc	 (2.x)
       include	a  malloc()  implementation  which  is tunable via environment
       variables.  When	MALLOC_CHECK_  is  set,	 a  special  (less  efficient)
       implementation  is used which is	designed to be tolerant	against	simple
       errors, such as double calls of free() with the same argument, or over-
       runs  of	 a  single byte	(off-by-one bugs).  Not	all such errors	can be
       protected against, however, and	memory	leaks  can  result.   If  MAL-
       LOC_CHECK_  is  set  to	0,  any	 detected  heap	corruption is silently
       ignored;	if set to 1, a diagnostic message is printed on	stderr;	if set
       to 2, abort(3) is called	immediately; if	set to 3, a diagnostic message
       is printed on stderr and	the program is aborted.	 Using a nonzero  MAL-
       LOC_CHECK_  value  can  be  useful because otherwise a crash may	happen
       much later, and the true	cause for the problem is  then	very  hard  to
       track down.

       By  default,  Linux  follows  an	optimistic memory allocation strategy.
       This means that when malloc() returns non-NULL there  is	 no  guarantee
       that  the  memory  really  is available.	 This is a really bad bug.  In
       case it turns out that the system is out	of memory, one	or  more  pro-
       cesses  will  be	 killed	 by the	infamous OOM killer.  In case Linux is
       employed	under circumstances where it would be less desirable  to  sud-
       denly lose some randomly	picked processes, and moreover the kernel ver-
       sion is sufficiently recent, one	can  switch  off  this	overcommitting
       behavior	using a	command	like:

	   # echo 2 > /proc/sys/vm/overcommit_memory

       See  also  the  kernel  Documentation  directory,  files	vm/overcommit-
       accounting and sysctl/vm.txt.

       brk(2), mmap(2),	alloca(3), posix_memalign(3)

       This page is part of release 3.25 of the	Linux  man-pages  project.   A
       description  of	the project, and information about reporting bugs, can
       be found	at

GNU				  2009-01-13			     MALLOC(3)


Want to link to this manual page? Use this URL:

home | help