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

  man pages->IRIX man pages -> malloc (3x)              


MALLOC(3X)							    MALLOC(3X)

NAME    [Toc]    [Back]

     malloc, free, realloc, calloc, mallopt, mallinfo, mallocblksize,
     recalloc, memalign	- fast main memory allocator

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <malloc.h>

     void *malloc (size_t size);

     void free (void *ptr);

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

     void *calloc (size_t nelem, size_t	elsize);

     int mallopt (int cmd, int value);

     struct mallinfo mallinfo(void);

     size_t mallocblksize (void	*ptr);

     void *recalloc (void *ptr,	size_t nelem, size_t elsize);

     void *memalign (size_t align, size_t size);

DESCRIPTION    [Toc]    [Back]

     malloc and	free provide a simple general-purpose memory allocation
     package, which is more flexible than the malloc(3c) package and,
     depending on an application's usage, may provide better performance.  It
     is	found in the library ``libmalloc.so'', and is loaded if	the option
     ``-lmalloc'' is used with cc(1) or	ld(1).

     malloc returns a pointer to a block of at least size bytes	suitably
     aligned for any use.

     The argument to free is a pointer to a block previously allocated by
     malloc; after free	is performed this space	is made	available for further
     allocation, and its contents are destroyed	(see mallopt below for a way
     to	change this behavior).

     Undefined results will occur if the space assigned	by malloc is overrun
     or	if some	random number is handed	to free.  It is	always permitted to
     pass NULL to free.

     realloc changes the size of the block pointed to 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.  In the special case
     of	a null ptr, realloc degenerates	to malloc.  A zero size	causes the
     passed block to be	freed.

									Page 1

MALLOC(3X)							    MALLOC(3X)

     calloc allocates space for	an array of nelem elements of size elsize.
     The space is initialized to zeros.

     recalloc combines realloc and calloc.  If the size	of the block
     increases,	any new	bytes are initialized to zero.	Note that for this to
     work properly, all	allocations of a given pointer must go through
     recalloc.	If the original	pointer	was allocated with either malloc,
     calloc, or	realloc	some new bytes may not be set properly to zero.

     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 align.  Note: the value
     of	align must be a	multiple of a word (for	64 bit objects,	a doubleword,)
     and must be greater than or equal to the size of a	word, or, for 64 bit
     objects, the size of a doubleword.

     mallocblksize returns the actual size of the block	pointed	to by ptr.
     The returned size may be greater than the original	requested size due to
     padding and alignment.

     mallopt provides for control over the allocation algorithm.  The
     available values for cmd are:

     M_MXFAST Set maxfast to value.  The algorithm allocates all blocks	at or
	      below the	size of	maxfast	in large groups	and then doles them
	      out very quickly.	 The default value for maxfast is 28.

     M_NLBLKS Set numlblks to value.  The above	mentioned ``large groups''
	      each contain numlblks blocks. numlblks must be greater than 0.
	      The default value	for numlblks is	100.

     M_GRAIN  Set grain	to value.  Requests less than or equal to maxfast will
	      have the size of a pointer added to them and be rounded up to
	      the next multiple	of grain.  value will be rounded up to a
	      multiple of the alignment	size (8	bytes for 32 bit programs, 16
	      bytes for	64 bit programs) when grain is set.  grain must	be
	      greater than 0.  The default value of grain is 8 for 32 bit
	      programs,	16 for 64 bit programs.

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

     M_DEBUG  Turns debug checking on if value is not equal to 0, otherwise
	      turns debug checking off.	 When debugging	is on, each call to
	      malloc and free causes the entire	malloc arena to	be scanned and
	      checked for consistency.	This option may	be invoked at any
	      time.  Note that when debug checking is on, the performance of
	      malloc is	reduced	considerably.  If corruption is	detected in
	      the arena, the checking code calls abort(3C).  This usually
	      results in the calling process exiting and leaving a core	file
	      in its current directory.

									Page 2

MALLOC(3X)							    MALLOC(3X)

     M_BLKSZ  When malloc requires additional space, it	uses sbrk(2) to
	      allocate enough memory for the current malloc request rounded up
	      to a minimum size	(default is 8K).  The new size is set to value
	      after it has been	rounded	up to the current block	alignment.
	      value must be at least 512 bytes.	 If a lot of space is to be
	      allocated, setting the size larger can cut down on the system
	      overhead.	 This option may be invoked at any time.

     M_MXCHK  By default, malloc trades	off time versus	space -	if anywhere in
	      the arena	there is a block of the	appropriate size, malloc will
	      find and return it.  If the arena	has become fragmented due to
	      many mallocs and frees, it is possible that malloc will have to
	      search through many blocks to find one of	the appropriate	size.
	      If the arena is severely fragmented, the average malloc time can
	      be on the	order of tens of milliseconds (as opposed to a normal
	      average of tens of microseconds).	 This option allows the	user
	      to place a limit on the number of	blocks that malloc will	search
	      through before allocating	a new block of space from the system.
	      Small values (less than 50) can cause much more memory to	be
	      allocated.  Values around	100 (the default) cause	very uniform
	      response time, with a small space	penalty.  This option may be
	      invoked at any time.

     M_FREEHD When value is not	zero, free, recalloc, and realloc will place
	      any freed	memory in the front of the free	list(s)	instead	of at
	      the end (which is	the default).  Some applications will benefit
	      in processing speed and space compaction by having freed memory
	      placed at	the beginning of the free list(s).

	      With this	option,	all blocks that	are freed are set to value.
	      This option may be set at	any time, but there is no way to turn
	      it off.  That part of the	beginning of a freed block which is
	      used for internal	pointers will of course	not be set to value.

     These values are defined in the <malloc.h>	header file.

     mallopt may be called repeatedly, but, for	most commands, may not be
     called after the first small block	is allocated.

     mallinfo provides instrumentation describing space	usage.	It returns the
     structure (defined	in <malloc.h>):

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

									Page 3

MALLOC(3X)							    MALLOC(3X)

	     int fordblks;	/* space in free ordinary blocks */
	     int keepcost;	/* space penalty if keep option	*/
				/* is used */
     For example, an application wishing to determine how many bytes it	has
     currently malloc'd	should add the usmblks and uordblks fields.  That
     total may also include some space that malloc allocates internally	for
     its own use, and that extra space cannot be free'd.

     Each of the allocation routines returns a pointer to space	suitably
     aligned (after possible pointer coercion) for storage of any type of

SEE ALSO    [Toc]    [Back]

     brk(2), malloc(3C), memalign(3C), amalloc(3P), valloc(3C).

DIAGNOSTICS    [Toc]    [Back]

     malloc, recalloc, memalign, realloc and calloc return a NULL pointer if
     there is not enough available memory or size is 0.	 memalign will also
     return NULL if align is 0 or not a	4 byte multiple	(8 byte	multiple for
     64-bit programs).	When realloc or	recalloc returns NULL, the block
     pointed to	by ptr is left intact.	If mallopt is called after any
     allocation	(for most cmd arguments) or if cmd or value are	invalid, nonzero
 is returned.	Otherwise, it returns zero.

WARNINGS    [Toc]    [Back]

     Note that unlike malloc(3C), this package does not	preserve the contents
     of	a block	when it	is freed, unless the M_KEEP option of mallopt is used.
     Undocumented features of malloc(3C) have not been duplicated.

     Products, libraries, or commands that provide their own malloc package
     must provide all of the entry points listed above,	or the normal
     libmalloc or libc malloc entry point for the unimplmented routine(s) may
     be	called instead,	leading	to corrupted heaps, as it is unlikely that the
     internal details of the heap management will be the same.	If the package
     is	a replacement for the libc set,	but not	the libmalloc set, it is not
     necessary to supply the mallopt, mallinfo,	mallocblksize, or recalloc

									PPPPaaaaggggeeee 4444
[ Back ]
 Similar pages
Name OS Title
malloc IRIX main memory allocator
amalloc IRIX arbitrary arena main memory allocator
mem HP-UX main memory
alloca OpenBSD memory allocator
alloca FreeBSD memory allocator
alloca NetBSD memory allocator
alloca Linux memory allocator
FREE NetBSD kernel memory allocator
malloc Tru64 Provide a memory allocator
mallopt Tru64 Provide a memory allocator
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service