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

FreeBSD Manual Pages

  
 
  

home | help
LIBMPALLOC(3)			mpatrol	library			 LIBMPALLOC(3)

NAME
       libmpalloc - dynamic memory allocation replacement library

SYNOPSIS
       #include	<mpalloc.h>

       void *MP_MALLOC(void *ptr, size_t count,	typename type);
       void *MP_CALLOC(void *ptr, size_t count,	typename type);
       char *MP_STRDUP(char *ptr, const	char *str);
       void *MP_REALLOC(void *ptr, size_t count, typename type);
       void MP_FREE(void *ptr);
       __mp_failhandler	MP_FAILURE(__mp_failhandler func);

DESCRIPTION
       The mpalloc library contains release implementations of all of the mpa-
       trol library functions, with all	of its checking, debugging and tracing
       features	 disabled.   It	 is fully link-compatible with the mpatrol li-
       brary and so can	be linked in instead of	the mpatrol library  in	 order
       to quickly disable all of its features without requiring	a complete re-
       compilation of all of the source	files in a project.  It	also  contains
       implementations	of  the	MP_MALLOC family of functions that can be used
       in a release environment.

       All of the function definitions in mpatrol.h can	be disabled by	defin-
       ing the NDEBUG preprocessor macro, which	is the same macro used to con-
       trol the	behaviour of the assert	function.  If NDEBUG is	 defined  then
       no macro	redefinition of	functions will take place and all special mpa-
       trol library functions will evaluate to empty  statements.   The	 mpal-
       loc.h  header  file will	also be	included in this case.	It is intended
       that the	NDEBUG preprocessor macro be defined in	release	builds.

       The mpalloc library contains functional replacements  for  all  of  the
       mpatrol	library's dynamic memory allocation and	memory operation func-
       tions, mainly for use in	situations where not all of the	 source	 files
       in a project have been recompiled with the NDEBUG preprocessor macro in
       order to	remove mpatrol.	 However, not all of these  functions  can  be
       fully  implemented  using  ANSI	C and so may contain some limitations.
       The only	recommended solution for a final release is to perform a  com-
       plete recompile with NDEBUG defined.

FUNCTIONS
       The  following  6  functions are	provided as convenient alternatives to
       the ANSI	C dynamic memory allocation functions (although	strdup is  not
       strictly	 an  ANSI  C  function).  They are implemented as preprocessor
       macro functions which may evaluate their	arguments more than  once,  so
       extra  care  should  be	taken to avoid passing arguments with side-ef-
       fects.  None of the functions return NULL if no memory is available and
       instead	abort the program with a useful	error message indicating where
       the call	to allocate memory came	from and what was being	allocated.  To
       use these you should include the	mpalloc.h header file:

       MP_MALLOC
	      Allocates	 count uninitialised items of type type	from the heap,
	      sets ptr to the result and returns a  suitably-cast  pointer  to
	      the  first item of the allocation.  The pointer returned will be
	      suitably aligned for holding items of type type.	If count is  0
	      then  it	will  be  implicitly rounded up	to 1.  If there	is not
	      enough space in the heap then the	program	will be	aborted	 after
	      calling  the allocation failure handler, which by	default	writes
	      an appropriate error message to the standard error file  stream.
	      The  allocated memory in ptr must	be deallocated with MP_FREE or
	      reallocated with MP_REALLOC.

       MP_CALLOC
	      Allocates	count zero-initialised items of	 type  type  from  the
	      heap, sets ptr to	the result and returns a suitably-cast pointer
	      to the first item	of the allocation.  The	pointer	returned  will
	      be suitably aligned for holding items of type type.  If count is
	      0	then it	will be	implicitly rounded up to 1.  If	there  is  not
	      enough  space in the heap	then the program will be aborted after
	      calling the allocation failure handler, which by default	writes
	      an  appropriate error message to the standard error file stream.
	      The allocated memory in ptr must be deallocated with MP_FREE  or
	      reallocated with MP_REALLOC.

       MP_STRDUP
	      Allocates	 exactly  enough memory	from the heap to duplicate str
	      (including the terminating nul character), sets ptr to  the  re-
	      sult  and	 returns  a suitably-cast pointer to the first byte of
	      the allocation after copying str to the newly-allocated  memory.
	      The  pointer returned will have no alignment constraints and can
	      be used to store character data up to the	 length	 of  str.   If
	      there  is	 not enough space in the heap then the program will be
	      aborted after calling the	allocation failure handler,  which  by
	      default  writes an appropriate error message to the standard er-
	      ror file stream.	The allocated memory in	ptr  must  be  deallo-
	      cated with MP_FREE or reallocated	with MP_REALLOC.

       MP_REALLOC
	      Resizes the memory allocation beginning at ptr to	count items of
	      type type	and returns a suitably-cast pointer to the first  item
	      of  the  new allocation after copying ptr	to the newly-allocated
	      memory, which will be truncated if count	is  smaller  than  the
	      original number of items.	 The pointer returned will be suitably
	      aligned for holding items	of type	type.  If ptr is NULL then the
	      call  will  be  equivalent  to MP_MALLOC.	 If count is 0 then it
	      will be implicitly rounded up to 1.  If count  is	 greater  than
	      the original number of items then	the extra space	will be	filled
	      with uninitialised bytes.	 If there is not enough	space  in  the
	      heap  then the program will be aborted after calling the alloca-
	      tion failure handler, which by default writes an appropriate er-
	      ror  message  to	the standard error file	stream.	 The allocated
	      memory must be deallocated with MP_FREE and can  be  reallocated
	      again with MP_REALLOC.

       MP_FREE
	      Frees  the  memory allocation beginning at ptr so	the memory can
	      be reused	by another call	to allocate memory, and	 sets  ptr  to
	      NULL  after  freeing  the	memory.	 If ptr	is NULL	then no	memory
	      will be freed.

       MP_FAILURE
	      Installs an allocation failure handler specifically for use with
	      MP_MALLOC,  MP_CALLOC,  MP_STRDUP	 and  MP_REALLOC and returns a
	      pointer to the previously	installed handler,  normally  the  de-
	      fault handler if no handler had been previously installed.  This
	      will be called by	the above functions when there is  not	enough
	      space  in	the heap for them to satisfy their allocation request.
	      The default allocation failure handler will terminate  the  pro-
	      gram  after  writing an error message to the standard error file
	      stream indicating	where the  original  allocation	 request  took
	      place and	what was being allocated.

SEE ALSO
       mpatrol(1),  mprof(1),  mptrace(1), mleak(1), mpsym(1), mpedit(1), hex-
       words(1), libmpatrol(3),	malloc(3), assert(3).

       The mpatrol manual and reference	card.

       http://www.cbmamiga.demon.co.uk/mpatrol/

AUTHOR
       Graeme S. Roy <graeme.roy@analog.com>

COPYRIGHT
       Copyright (C) 1997-2002 Graeme S. Roy <graeme.roy@analog.com>

       This library is free software; you can redistribute it and/or modify it
       under  the terms	of the GNU Library General Public License as published
       by the Free Software Foundation;	either version 2 of  the  License,  or
       (at your	option)	any later version.

       This  library  is  distributed  in the hope that	it will	be useful, but
       WITHOUT ANY  WARRANTY;  without	even  the  implied  warranty  of  MER-
       CHANTABILITY  or	FITNESS	FOR A PARTICULAR PURPOSE.  See the GNU Library
       General Public License for more details.

       You should have received	a copy of the GNU Library General  Public  Li-
       cense along with	this library; if not, write to the Free	Software Foun-
       dation, Inc., 59	Temple Place, Suite 330, Boston, MA 02111-1307,	USA.

Release	1.4			8 January 2002			 LIBMPALLOC(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libmpalloc&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help