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

FreeBSD Manual Pages

  
 
  

home | help
MALLOC(3V)							    MALLOC(3V)

NAME
       malloc, free, realloc, calloc, cfree, memalign, valloc, mallocmap, mal-
       lopt, mallinfo, malloc_debug, malloc_verify, alloca - memory allocator

SYNOPSIS
       #include	<malloc.h>

       char *malloc(size)
       unsigned	size;

       int free(ptr)
       char *ptr;

       char *realloc(ptr, size)
       char *ptr;
       unsigned	size;

       char *calloc(nelem, elsize)
       unsigned	nelem, elsize;

       int cfree(ptr)
       char *ptr;

       char *memalign(alignment, size)
       unsigned	alignment;
       unsigned	size;

       char *valloc(size)
       unsigned	size;

       void mallocmap()

       int mallopt(cmd,	value)
       int cmd,	value;

       struct mallinfo mallinfo()

       #include	<alloca.h>

       char *alloca(size)
       int size;

SYSTEM V SYNOPSIS
       #include	<malloc.h>

       void *malloc(size)
       size_t size;

       void free(ptr)
       void *ptr;

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

       void *calloc(nelem, elsize)
       size_t nelem;
       size_t elsize;

       void *memalign(alignment, size)
       size_t alignment;
       size_t size;

       void *valloc(size)
       size_t size;

       The XPG2	versions of the	functions listed in this section are  declared
       as they are in SYNOPSIS above, except free(), which is declared as:

       void free(ptr)
       char *ptr;

DESCRIPTION
       These  routines	provide	 a  general-purpose memory allocation package.
       They maintain a table of	free blocks for	efficient allocation and  coa-
       lescing of free storage.	 When there is no suitable space already free,
       the allocation routines call sbrk() (see	brk(2))	 to  get  more	memory
       from the	system.

       Each  of	 the  allocation  routines returns a pointer to	space suitably
       aligned for storage of any type of object.  Each	returns	a NULL pointer
       if the request cannot be	completed (see DIAGNOSTICS).

       malloc()	 returns a pointer to a	block of at least size bytes, which is
       appropriately aligned.

       free() releases a  previously  allocated	 block.	  Its  argument	 is  a
       pointer	to  a  block previously	allocated by malloc(), calloc(), real-
       loc(), malloc(),	or memalign().

       realloc() changes the size of the block referenced by ptr to size bytes
       and returns a pointer to	the (possibly moved) block.  The contents will
       be unchanged up to the lesser of	the new	and old	sizes.	If  unable  to
       honor a reallocation request, realloc() leaves its first	argument unal-
       tered.  For backwards compatibility, realloc() accepts a	pointer	 to  a
       block  freed  since  the	 most recent call to malloc(), calloc(), real-
       loc(), valloc(),	or memalign().	Note: using  realloc()	with  a	 block
       freed  before  the  most	 recent	call to	malloc(), calloc(), realloc(),
       valloc(), or memalign() is an error.

       calloc()	uses malloc() to allocate space	for an array of	nelem elements
       of  size	 elsize, initializes the space to zeros, and returns a pointer
       to the initialized block.  The  block  can  be  freed  with  free()  or
       cfree().

       memalign()  allocates size bytes	on a specified alignment boundary, and
       returns a pointer to the	allocated block.  The value  of	 the  returned
       address	is  guaranteed to be an	even multiple of alignment.  Note: the
       value of	alignment must be a power of two, and must be greater than  or
       equal to	the size of a word.

       valloc(size) is equivalent to memalign(getpagesize(), size).

       mallocmap()  prints  a  map  of	the heap to the	standard output.  mal-
       locmap()	prints each block's address, size (in bytes) and status	 (free
       or  busy).  A block must	have a size that is no larger than the current
       extent of the heap.

       mallopt() allows	quick allocation of small blocks of memory.  mallopt()
       tells  subsequent calls to malloc() to allocate holding blocks contain-
       ing small blocks.  Under	this small block algorithm, a request to  mal-
       loc()  for a small block	of memory returns a pointer to one of the pre-
       allocated small blocks.	Different holding blocks are created as	needed
       for different sizes of small blocks.

       cmd may be one of the following values, defined in <malloc.h>:

       M_MXFAST	      Set the maximum size of blocks to	be allocated using the
		      small block algorithm (maxfast) to value.	 The algorithm
		      allocates	 all  blocks  smaller  than  maxfast  in large
		      groups and then doles them out very quickly.  Initially,
		      maxfast is 0 and the small block algorithm is disabled.

       M_NLBLKS	      Set the number of	small blocks in	a holding block	(numl-
		      blks) to value.  The holding blocks each	contain	 numl-
		      blks  blocks.  numlblks must be greater than 1.  The de-
		      fault value for numlblks is 100.

       M_GRAIN	      Set the granularity for small block requests (grain)  to
		      value.  The sizes	of all blocks smaller than maxfast are
		      rounded up to the	nearest	multiple of grain.  grain must
		      be  greater  than	 0.  The default value of grain	is the
		      smallest number of bytes which will allow	 alignment  of
		      any  data	 type.	When grain is set, value is rounded up
		      to a multiple of this default.

       M_KEEP	      Preserve data in a freed block until the next  malloc(),
		      realloc(),  or  calloc().	  This option is provided only
		      for compatibility	with the old version of	 malloc()  and
		      is not recommended.

       mallopt()  may  be  called  repeatedly, but may not be called after the
       first small block is allocated.

       mallinfo() can be used during program development to determine the best
       settings	 for  the parameters set by mallopt().	Do not call mallinfo()
       until after a call to malloc().	mallinfo()  provides  information  de-
       scribing	 space	usage.	 It  returns  a	mallinfo structure, defined in
       <malloc.h> as:

	      struct mallinfo {
		     int arena;	    /* total space in arena */
		     int ordblks;   /* number of ordinary blocks */
		     int smblks;    /* number of small blocks */
		     int hblks;	    /* number of holding blocks	*/
		     int hblkhd;    /* space in	holding	block headers */
		     int usmblks;   /* space in	small blocks in	use */
		     int fsmblks;   /* space in	free small blocks */
		     int uordblks;  /* space in	ordinary blocks	in use */
		     int fordblks;  /* space in	free ordinary blocks */
		     int keepcost;  /* cost of enabling	keep option */

		     int mxfast;    /* max size	of small blocks	*/
		     int nlblks;    /* number of small blocks in a holding block */
		     int grain;	    /* small block rounding factor */
		     int uordbytes; /* space (including	overhead) allocated in ord. blks */
		     int allocated; /* number of ordinary blocks allocated */
		     int treeoverhead;	 /* bytes used in maintaining the free tree */
	      };

       alloca()	allocates size bytes of	 space	in  the	 stack	frame  of  the
       caller,	and  returns a pointer to the allocated	block.	This temporary
       space is	automatically freed when the caller returns.  Note that	if the
       allocated block is beyond the current stack limit, the resulting	behav-
       ior is undefined.

       malloc(), realloc(), memalign() and valloc() return a non-NULL  pointer
       if  size	 is 0, and calloc() returns a non-NULL pointer if nelem	or el-
       size is 0, but these pointers should not	be dereferenced.

       Note: Always cast the value returned by malloc(), realloc(),  calloc(),
       memalign(), valloc() or alloca().

SYSTEM V DESCRIPTION
       The  XPG2  versions of malloc(),	realloc(), memalign() and valloc() re-
       turn NULL if size is 0.	The XPG2 version of calloc() returns  NULL  if
       nelem or	elsize is 0.

RETURN VALUES
       On success, malloc(), calloc(), realloc(), memalign(), valloc() and al-
       loca() return a pointer to space	suitably aligned for  storage  of  any
       type of object.	On failure, they return	NULL.

       free() and cfree() return:

       1      on success.

       0      on failure and set errno to indicate the error.

       mallopt() returns 0 on success.	If mallopt() is	called after the allo-
       cation of a small block,	or if cmd or value is invalid,	it  returns  a
       non-zero	value.

       mallinfo() returns a struct mallinfo.

SYSTEM V RETURN	VALUES
       If  size	is 0, the XPG2 versions	of malloc(), realloc(),	memalign() and
       valloc()	return NULL.

       If nelem	or elsize is 0,	the XPG2 version of calloc() returns NULL.

       free() does not return a	value.

ERRORS
       malloc(),  calloc(),  realloc(),	 valloc(),  memalign(),	 cfree(),  and
       free() will each	fail if	one or more of the following are true:

       EINVAL	      An invalid argument was specified.

		      The value	of ptr passed to free(), cfree(), or realloc()
		      was not a	pointer	to a  block  previously	 allocated  by
		      malloc(),	calloc(), realloc(), valloc(), or memalign().

		      The  allocation  heap  is	 found to have been corrupted.
		      More detailed information	may be	obtained  by  enabling
		      range checks using malloc_debug().

       ENOMEM	      size bytes of memory could not be	allocated.

FILES
       /usr/lib/debug/malloc.o	diagnostic versions of malloc()	routines.
       /usr/lib/debug/mallocmap.o
				routines to print a map	of the heap.

SEE ALSO
       csh(1), ld(1), brk(2), getrlimit(2), sigvec(2), sigstack(2)

       Stephenson, C.J., Fast Fits, in Proceedings of the ACM 9th Symposium on
       Operating Systems, SIGOPS Operating Systems Review, vol.	17, no.	5, Oc-
       tober 1983.
       Core Wars, in Scientific	American, May 1984.

DIAGNOSTICS
       More  detailed diagnostics can be made available	to programs using mal-
       loc(), calloc(),	realloc(), valloc(), memalign(), cfree(), and  free(),
       by  including  a	 special  relocatable  object  file  at	link time (see
       FILES).	This file also provides	routines for control of	error handling
       and  diagnosis, as defined below.  Note:	these routines are not defined
       in the standard library.

	      int malloc_debug(level)
	      int level;

	      int malloc_verify()

       malloc_debug() sets the level of	error diagnosis	and  reporting	during
       subsequent  calls  to  malloc(),	 calloc(),  realloc(), valloc(), mema-
       lign(), cfree(),	and free().  The value of level	is interpreted as fol-
       lows:

       Level 0		   malloc(),   calloc(),  realloc(),  valloc(),	 mema-
			   lign(), cfree(), and	free() behave the same	as  in
			   the standard	library.

       Level 1		   The	routines  abort	with a message to the standard
			   error if errors are detected	in arguments or	in the
			   heap.   If  a bad block is encountered, its address
			   and size are	included in the	message.

       Level 2		   Same	as level 1, except that	the entire heap	is ex-
			   amined on every call	to the above routines.

       malloc_debug()  returns	the  previous error diagnostic level.  The de-
       fault level is 1.

       malloc_verify() attempts	to determine if	the heap has  been  corrupted.
       It  scans  all blocks in	the heap (both free and	allocated) looking for
       strange addresses or absurd sizes, and also checks for  inconsistencies
       in  the free space table.  malloc_verify() returns 1 if all checks pass
       without error, and otherwise returns 0.	The checks can take a signifi-
       cant amount of time, so it should not be	used indiscriminately.

WARNINGS
       alloca()	 is  machine-,	compiler-,  and	most of	all, system-dependent.
       Its  use	 is  strongly  discouraged.   See   getrlimit(2),   sigvec(2),
       sigstack(2), csh(1), and	ld(1).

NOTES
       Because	malloc(), realloc(), memalign()	and valloc() return a non-NULL
       pointer if size is 0, and calloc() returns a non-NULL pointer if	 nelem
       or elsize is 0, a zero size need	not be treated as a special case if it
       should be passed	to these functions unpredictably.  Also,  the  pointer
       returned	 by these functions may	be passed to subsequent	invocations of
       realloc().

SYSTEM V NOTES
       The XPG2	versions of the	allocation routines return NULL	when passed  a
       zero size (see SYSTEM V DESCRIPTION above).

BUGS
       Since  realloc()	accepts	a pointer to a block freed since the last call
       to malloc(), calloc(), realloc(), valloc(), or memalign(),  a  degrada-
       tion of performance results.  The semantics of free() should be changed
       so that the contents of a previously freed block	are undefined.

				24 January 1990			    MALLOC(3V)

NAME | SYNOPSIS | SYSTEM V SYNOPSIS | DESCRIPTION | SYSTEM V DESCRIPTION | RETURN VALUES | SYSTEM V RETURN VALUES | ERRORS | FILES | SEE ALSO | DIAGNOSTICS | WARNINGS | NOTES | SYSTEM V NOTES | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=malloc_debug&sektion=3&manpath=SunOS+4.1.3>

home | help