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

FreeBSD Manual Pages


home | help
malloc(3C)							    malloc(3C)

       malloc(), free(), realloc(), calloc(), valloc(),	mallopt(), mallinfo(),
       memorymap(), alloca() - main memory allocator

       The functionality in the	old malloc(3X) package has  been  incorporated
       into malloc(3C).	 The library corresponding to the linker option	is now
       an empty	library.  Makefiles that reference this	library	will  continue
       to work.

   Obsolescent Interfaces
       has been	deprecated at HP-UX 11.11 and is now obsolete.

       The  functions described	in this	manual entry provide a simple, general
       purpose memory allocation package:

	      Allocates	space for a block of at	least
			       size bytes, but does not	initialize the space.

	      Allocates	space for an array of
			       nelem elements, each of size elsize bytes,  and
			       initializes  the	space to zeros.	 Actual	amount
			       of space	allocated will be at least nelem * el-
			       size bytes.

	      Changes the size of the block pointed to by
			       ptr  to size bytes and returns a	pointer	to the
			       (possibly moved)	block.	Existing contents  are
			       unchanged  up  to the lesser of the new and old
			       sizes.  If ptr is a NULL	pointer, behaves  like
			       for  the	 specified  size.  If size is zero and
			       ptr is not a NULL pointer, the object it	points
			       to  is  freed  and NULL is returned.  of	blocks
			       with special alignments,	such as	those  created
			       by is not supported.

	      Allocates	space for a block of at	least
			       size  bytes starting on a boundary aligned to a
			       multiple	of the value returned  by  (__SC_PAGE-
			       SIZE).  This space is uninitialized.

	      Deallocates the space pointed to by
			       ptr  (a pointer to a block previously allocated
			       by or and makes the space available for further
			       allocation.   If	 ptr is	a NULL pointer,	no ac-
			       tion occurs.

	      Provides for control over	the allocation algorithm
			       and other options in  the  malloc(3C)  package.
			       The available values for	cmd are:

			       Set	      maxfast to value.	 The algorithm
					      allocates	all blocks  below  the
					      size of maxfast in large groups,
					      then   doles   them   out	  very
					      quickly.	 The default value for
					      maxfast is zero.

			       Set	      numlblks to  value.   The	 above
					      mentioned	 ``large groups'' each
					      contain numlblks blocks.	 numl-
					      blks  must  be  greater  than 1.
					      The default value	 for  numlblks

			       Set	      grain  to	 value.	  The sizes of
					      all blocks smaller than  maxfast
					      are  considered to be rounded up
					      to  the  nearest	 multiple   of
					      grain.   grain  must  be greater
					      than zero.  The default value of
					      grain  is	the smallest number of
					      bytes   that   can   accommodate
					      alignment	  of  any  data	 type.
					      value is rounded up to a	multi-
					      ple of the default when grain is

			       Preserve	data in	a freed	block until the	next
					      or This option is	provided  only
					      for  compatibility  with the old
					      version of  and  is  not	recom-

			       Block all blockable signals in
					      and  This	option is provided for
					      those who	need to	 write	signal
					      handlers	that  allocate memory.
					      When set,	 the  malloc(3C)  rou-
					      tines  can be called from	within
					      signal handlers (they become re-
					      entrant).	  Default action is to
					      block all	blockable signals.

			       Do not block all	blockable signals in
					      and This option  cancels	signal
					      blocking	initiated  by  the op-

			       These values are	defined	in the header file.

			       can be called repeatedly; but  once  the	 first
			       small block is allocated, it is not possible to
			       change the and values.

	      Provides instrumentation describing space	usage,
			       but cannot be  called  until  the  first	 small
			       block is	allocated.  It returns the structure

			       The structure is	defined	in the header file.

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

	      Displays the contents of the memory allocator
			       for  HP-UX  32-bit  operating  systems only.  A
			       list of addresses  and  block  descriptions  is
			       written	(using	to  standard  output.	If the
			       value of	the show_stats parameter is 1, statis-
			       tics concerning number of blocks	and sizes used
			       will also be written.  If the  value  is	 zero,
			       only the	memory map will	be written.

			       The  addresses  and  sizes displayed by may not
			       correspond to those requested  by  an  applica-
			       tion.   The  size  of a block (as viewed	by the
			       allocator) includes header information and pad-
			       ding  to	properly align the block.  The address
			       is also offset by a certain amount to  accommo-
			       date the	header information.

			       has  been  deprecated at	HP-UX 11.11 and	is now

	      Allocates	space from the stack of	the caller
			       for a block of at least size  bytes,  but  does
			       not  initialize	the space.  The	space is auto-
			       matically freed when the	calling	routine	exits.

			       Memory returned by is not related to memory al-
			       located	by  other memory allocation functions.
			       Behavior	of addresses returned by as parameters
			       to other	memory functions is undefined.

			       The  implementation  of	this routine is	system
			       dependent and its use is	discouraged.

       Upon successful completion, and return  a  pointer  to  space  suitably
       aligned	(after	possible  pointer coercion) for	storage	of any type of
       object.	Otherwise, they	return a NULL  pointer.	  If  returns  a  NULL
       pointer,	the memory pointed to by the original pointer is left intact.

       returns zero for	success	and nonzero for	failure.

       and  return  a  NULL pointer if there is	no available memory, or	if the
       memory managed by has been detectably corrupted.	 This memory  may  be-
       come  corrupted	if data	is stored outside the bounds of	a block, or if
       an invalid pointer (a pointer not generated by or is passed as an argu-
       ment to or

       If  is  called after any	allocation of a	small block and	cmd is not set
       to or or	if cmd or value	is invalid, nonzero is	returned.   Otherwise,
       it returns zero.

	      [ENOMEM]	       and  set	 to  ENOMEM  and return	a NULL pointer
			       when an out-of-memory condition arises.

	      [EINVAL]	       and set to EINVAL and  return  a	 NULL  pointer
			       when  the  memory being managed by has been de-
			       tectably	corrupted.

       The performance of the family can be tuned via  two  environment	 vari-
       ables, and and three new	global variables, and

       For  threaded  applications, uses multiple arenas. Memory requests from
       different threads are handled by	different arenas.  can be used to  ad-
       just the	number of arenas and how many pages each time an arena expands
       itself (the expansion factor), assuming that  the  page	size  is  4096
       bytes.  In general, the more threads in an application, the more	arenas
       should be used for better performance. The number of arenas can be from
       1  to 64	for threaded applications. For non-threaded applications, only
       one arena is used. If the environment variable is not set, or the  num-
       ber  of	arenas	is set to be out of the	range, the default number of 8
       will be used. The expansion factor is from 1 to 4096, default value  is
       32. Again, if the factor	is out of the range, the default value will be

       Here is an example of how to use

       This means that the number of arenas is 16, and the expansion  size  is
       8*4096 bytes.  In general, the more arenas you use, the smaller the ex-
       pansion factor should be, and vice versa.

       is used to turn on the small block allocator, and to set	up  parameters
       for  the	 small	block allocator, namely, maxfast, grain, and numlblks.
       Applications with small block allocator turned on  usually  run	faster
       than with it turned off.	Small block allocator can be turned on through
       however,	it is not early	enough for C++/Java applications. The environ-
       ment  variable  turns it	on before the application starts. The call can
       still be	used the same way. If the environment variable is set, and  no
       small  block  allocator	has  been used,	the subsequent calls can still
       overwrite whatever is set through If the	environment variable  is  set,
       and small block allocator has been used,	then will have no effect.

       To use this environment variable,

       This  means that	the maxfast size is 512, the number of small blocks is
       100, and	the grain size is 16.  You have	to supply all 3	values,	and in
       that order. If not, the default values will be used instead.

       has no effects on non-threaded applications, while has.

       The three new global variables, and are introduced to over-ride the en-
       vironment option. When these three variables are	initialized within  an
       application,  has  no  effect. This way,	a finely tuned application can
       lock in performance across different user environments. However,	 as  a
       subsequent call to before any block of memory was allocated will	change
       the behavior. By	default, these three variables will be initialized  to
       zero at start up. It is the same	as setting them	to

       By  default,  SBA (Small	Block Allocation) is turned on.	 This may con-
       tribute to better application performance. A user can set

       This will turn off SBA.

       For all other possible values, please refer to

       NOTE: Modifying these variables increases the chances of	surfacing  ex-
       isting user memory defects such as buffer overrun.

       functions  use  and  (see  brk(2))  to  increase	the address space of a
       process.	 Therefore, an application program that	uses or	must  not  use
       them  to	 decrease  the	address	space, because this confuses the func-

       and do not check	their pointer argument for validity.

       The following actions are  considered  bad  programming	practices  and
       should  not  be done.  The results are unpredictable, probably undesir-
       able and	not supported.	Examples of undesirable	results	 are  loss  of
       data, memory fault, bus error or	infinite loop.

	      o	 Attempting  to	 or a pointer not generated as the result of a
		 call to or

	      o	 Reading or writing data outside the boundaries	 of  an	 allo-
		 cated block.

	      o	 Attempting to an aligned block	such as	the result of

       The  following  actions are strongly discouraged	and may	be unsupported
       in a future version of

	      o	 Attempting to the same	block twice.

	      o	 Depending on unmodified contents of a block after it has been

	      o	 Attempting to a block after it	is freed.

       Undocumented features of	earlier	memory allocators have not been	dupli-
       cated.  Applications which used any of the above	bad programming	 prac-
       tices or	discouraged practices are not guaranteed to continue function-
       ing at future releases.

   Obsolescent Interfaces
       has been	deprecated at HP-UX 11.11 and is now obsolete.	 The  function
       is more useful for statistics.

       The  only  external difference between the old malloc(3X) allocator and
       the malloc(3C) allocator	is that	the old	allocator would	return a  NULL
       pointer	for a request of zero bytes.  The malloc(3C) allocator returns
       a valid memory address.	This is	not a concern for most applications.

       By default, SBA (Small Block Allocation)	is turned on for  IPF  systems
       and  is	turned	off  for PA systems.  This was due to performance con-
       cerns. Please refer to the section of this man page for details.

       brk(2), errno(2), thread_safety(5).



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

home | help