free man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

malloc(3)							     malloc(3)

       alloca, calloc, free, mallinfo, malloc, mallopt, realloc, valloc - Pro‐
       vide a memory allocator

       #include <stdlib.h>

       void *calloc(
	       size_t num_of_elts,
	       size_t elt_size ); void free(
	       void *pointer ); void *malloc(
	       size_t size ); void *realloc
	       void *pointer,
	       size_t size ); void *valloc(
	       size_t size );

       The following function definitions do not conform to current  standards
       and are supported only for backward compatibility.  char *valloc(
	       size_t size );

       #include <alloca.h>

       void *alloca(
	       int size );

       The  following function definitions are provided only for System V com‐

       #include <malloc.h>

       struct mallinfo mallinfo(
	       void ); int mallopt(
	       int command,
	       int value );

       Standard C Library (libc)

       [Tru64 UNIX]  Dense Malloc Library (libdensemalloc)

       Interfaces documented on this reference page conform to industry	 stan‐
       dards as follows:

       calloc(), free(), malloc(), realloc(), valloc(): XSH5.0

       Refer  to  the  standards(5)  reference page for more information about
       industry standards and associated tags.

       Specifies a number of bytes of memory.  Points to the block  of	memory
       that  was  returned  by the malloc() or calloc() function.  Specifies a
       mallopt() function command.  Specifies M_MXFAST, M_NLBLKS, M_GRAIN,  or
       M_KEEP.	 Specifies the number of elements in the array.	 Specifies the
       size of each element in the array.

       The malloc() and free() functions  provide  a  simple,  general-purpose
       memory allocation package.


       See also the subsection “Using the densemalloc Library” for information
       on using libdensemalloc to improve the performance of certain programs.

       The malloc() function returns a pointer to a  block  of	memory	of  at
       least the number of bytes specified by the size parameter. The block is
       aligned so that it can be used for any type of data, and	 the  contents
       of  the	memory	are  undefined. If the size parameter is 0 (zero), the
       malloc() function returns a null pointer.

       The free() function frees the block of memory pointed to by the pointer
       parameter  for further allocation.  The block pointed to by the pointer
       parameter must have been previously allocated as follows: By either the
       malloc(), realloc(), or calloc() functions.  [XPG4-UNIX]	 By either the
       malloc(), realloc(), calloc(), or valloc() functions.

       The realloc() function changes the size of the block of memory  pointed
       to  by  the  pointer  parameter to the number of bytes specified by the
       size parameter, and returns a pointer to the block. The contents of the
       block  remain  unchanged up to the lesser of the old and new sizes, and
       the contents of any memory added beyond the limit of the	 old  size  is
       undefined.  If  necessary, a new block is allocated, and data is copied
       to it. If the pointer parameter is a null pointer, the realloc()	 func‐
       tion  simply  allocates	a new block of the requested size. If the size
       parameter is 0 (zero) and pointer is not a null pointer, the  realloc()
       function frees the specified block.

       The  calloc()  function allocates space for an array with the number of
       elements specified by the num_of_elts parameter, where each element  is
       of  the size specified by the elt_size parameter. The space is initial‐
       ized to zeros.

       [Tru64 UNIX]  The alloca() function allocates the number	 of  bytes  of
       space specified by the size parameter in the stack frame of the caller.
       This space is automatically freed when the  function  that  called  the
       alloca()	 function returns to its caller. The contents of the memory is


       The alloca() function requires inclusion of  <alloca.h>.	 Without  this
       header  file,  alloca()	allocates  memory  in  the heap instead of the
       stack; this memory is not necessarily freed when	 the  calling  routine

       The  valloc() function has the same effect as malloc(), except that the
       allocated memory is automatically aligned to a page boundary (that  is,
       the value returned by a call to getpagesize()).

       The mallopt() and mallinfo() functions are intended to allow tuning the
       allocation algorithm at execution time. They have minimal effect on the
       current	Tru64 UNIX implementation of memory allocation.	 See the NOTES
       section for details.

       The mallopt() function can be called repeatedly, but parameters	cannot
       be  changed  after  the	first  small block is allocated from a holding
       block. If the mallopt() function is called again after the first	 small
       block is allocated, it returns an error.

       The  mallinfo()	function  can  be  used	 during program development to
       determine the best settings of these parameters for a particular appli‐
       cation.	It  must only be called after some storage has been allocated.
       Information  describing	space  usage  is  returned.   Refer   to   the
       /usr/include/malloc.h  header  file  for details of the mallinfo struc‐

   Tuning Memory Allocation

       See also the subsection “Using the densemalloc Library” for information
       on the densemalloc tuning variables.

       The behavior of these memory allocation functions can be tuned to opti‐
       mize their performance in a particular application.

       The following variables control how the functions  operate.  Note  that
       these  variables	 and  their  effects are specific to the current Tru64
       UNIX memory allocation implementation. The  default  values  for	 these
       variables  are  specified  by  libc.  To	 specify values other than the
       defaults, create a module containing definitions for the	 complete  set
       of  variables  and  include  that  module  in your compilation. (If you
       define only some of these  variables,  your  compilation	 will  produce
       ``multiply  defined''  errors  if  you link the program nonshared.) For
       each variable in this list, the default value is	 indicated  after  the
       equal sign.

       Except  where  noted,  these  variables	also  apply  to	 the functions
       described in amalloc(3).	 The variable __delayed_free is used to	 cause
       the  free  function  to use a “delay” slot (of size 1). This means that
       any time you call free, it saves your pointer and actually  frees  what
       you last called free with. This is intended to compensate for misuse of
       realloc, where the user frees a pointer and then calls realloc with it.

	      Because the delay slot is shared across all threads,  this  fea‐
	      ture  will  not  provide	reliable  protection for multithreaded
	      applications. Sharing the delay slot also results	 in  it	 being
	      accessed internally with atomic instruction sequences, which can
	      create a bottleneck on multiCPU systems.

	      A value of 1 turns this feature on for single-threaded  applica‐
	      tions.   A  value of 2 turns this feature on for both single and
	      multithreaded applications.  A value of 0 (zero) turns this fea‐
	      ture  off. All other values cause undefined behavior. It is rec‐
	      ommended that all multithreaded applications should try  to  use
	      the  value  0 or 1. The default value of 2 will change to 1 in a
	      future release.  The variable  __fast_free_max  is  the  maximum
	      number  of  small	 buffers  that malloc retains in the free list
	      without attempting to coalesce. This number is further  adjusted
	      by  the  number  of megabytes in the user heap. As the heap size
	      increases, this number in reduced by 1 for each 10 MB of heap so
	      that  at	a  heap size of 130 MB only one buffer of each type is
	      held in the free list.

	      Increasing the value of __fast_free_max increases both execution
	      speed and overhead (the size of the heap in relation to the mem‐
	      ory requested).  The variable __first_fit is currently  intended
	      only  for	 performance  critical	multithreaded applications. It
	      should not be used with single threaded applications. Its	 value
	      is  used	to  allow  malloc  and	amalloc to skip up to a larger
	      internal cache list if the optimum node size list is found to be
	      in use by another thread. The allowed values are 0, 1, and 2. Do
	      not use any other value. A value of 0 disables this  feature.  A
	      value  of	 1 allows the next larger list to be used, and a value
	      of 2 allows the next list after that  to	also  be  used	(three
	      lists in total).

	      Increasing  the value of __first_fit can increase both execution
	      speed and memory consumption of multithreaded applications  mak‐
	      ing  heavy concurrent use of either malloc functions or the same
	      arena with amalloc functions.  The __madvisor variable  controls
	      how  malloc communicates memory usage information to the kernel.
	      Permissible values for __madvisor are 0 and 1. If	 the  variable
	      value is 1, any physical memory associated with the virtual mem‐
	      ory range is removed, reducing the resident set size (RSS).  The
	      kernel does not need to swap this memory out.

	      Setting  a  value	 of  1	for  __madvisor	 results  in a trivial
	      decrease in execution speed. If execution	 speed	is  important,
	      leave  the setting at the default value of 0. (Does not apply to
	      amalloc functions.)  The __max_cache variable suggests the  num‐
	      ber of internal cache (lookaside) lists to be used by malloc and
	      amalloc. Each list contains blocks within the same size range. A
	      larger  value  of	 __max_cache  causes  the  internal caching of
	      larger sized blocks. The currently  allowable  values  for  this
	      variable are 15, 18, 21, 24, and 27. Do not use any other value.
	      The given values correspond to lists containing nodes up to 632,
	      1272,  2552,  5112,  and	10232 bytes in size, respectively. The
	      maximum length of the lists is determined by the __fast_free_max
	      variable described elsewhere in this section.

	      Application  requests  for  storage that can be satisfied from a
	      node on a cache list typically happen somewhat faster than those
	      that  cannot. Increasing the value of this variable can increase
	      both the execution speed	and  that  memory  consumption	of  an
	      application  that	 allocates nodes in the given size range.  The
	      variable __mingrow is the minimum size that the heap is  allowed
	      to  grow in response to any request for a buffer that would grow
	      the heap. The amount to grow  is	the  larger  of	 __mingrow  or
	      __mingrowfactor * heap_size_in_bytes. The value of this variable
	      is used in whole-page increments; any value that is not an inte‐
	      gral  multiple  of  the  page size is rounded upward to the next
	      whole number of pages.

	      The __mingrow and __mingrowfactor variables control  compromises
	      between  speed  and  memory  usage; increasing either or both of
	      them increases overhead but decreases execution time.  The vari‐
	      able  __mingrowfactor is the minimum fraction that the heap will
	      be allowed to grow. The actual amount grown  is  the  larger  of
	      __mingrow or __mingrowfactor * heap_size_in_bytes.  The variable
	      __minshrink is the minimum size that  the	 heap  is  allowed  to
	      shrink  in  response  to	the freeing of space at the end of the
	      heap. The heap will shrink if the space is greater  than	__min‐
	      shrink and greater than __minshrinkfactor * heap_size_in_bytes.

	      This  variable  has no effect unless __noshrink is 0.  The vari‐
	      able __minshrinkfactor is the minimum fraction that the heap  is
	      allowed to shrink in response to the freeing of space at the end
	      of the heap. The heap will shrink if the space is	 greater  than
	      __minshrink     and    greater	than	__minshrinkfactor    *

	      This variable has no effect unless __noshrink is 0.   The	 vari‐
	      able  __noshrink	controls management of the heap size (which in
	      turn controls the size of the required swap area). As  the  user
	      makes  calls  to free() or realloc(), the memory associated with
	      the call can be put back into the pool of free memory. Permissi‐
	      ble values for __noshrink are 0 and 1.

	      If  the  memory that is freed resides at the end of the heap and
	      meets the constraints of __minshrink and	__minshrinkfactor,  it
	      can  be  returned to the kernel by sbrk(nnn) if __noshrink is 0.
	      If __noshrink is 1, no attempts are made	to  return  the	 freed

	      Set  __noshrink  to  1 if execution speed is more important than
	      economy of memory usage.	The variable __sbrk_override  controls
	      the  manner  in which the heap growth is obtained. If this vari‐
	      able is set to 1 (the default) and the call to sbrk to grow  the
	      heap  fails, a call is made to mmap to attempt to obtain memory.
	      This technique is extremely valuable to programs running in taso
	      mode.  (Does not apply to amalloc functions.) If the variable is
	      set to 0, no call is made to mmap if the call to sbrk fails.


	      The use of this method to obtain heap space will	cause  sbrk(0)
	      to  return  a  value  that  does not reflect the true end of the
	      heap.  The __small_buff variable affects	how  malloc  allocates
	      space for extremely small buffers.  If the variable is 1, malloc
	      allocates 24 bytes for requests of 1 to 15 bytes; if  it	is  0,
	      the  buffer  allocated  is  32  bytes.  The  size of 32 bytes is
	      required by X/Open guidelines specifying that a buffer  must  be
	      so  aligned  that it can be assigned to any type of object. Per‐
	      missible values for __small_buff are 0 and 1.

	      If the process is using a great many small (1 to 15  byte)  buf‐
	      fers,  setting  __small_buff  to	1  reduces heap overhead.  The
	      variable __taso_mode is set to 1 to indicate that the program is
	      executing	 in taso mode. If the variable is set to 1, the point‐
	      ers returned by malloc and realloc are bounds  checked  and  the
	      ENOMEM error is returned if the pointer exceeds MAXINT.

   Using the densemalloc Library
       The  densemalloc	 library  provides an alternate set of malloc routines
       that implement a “dense malloc” memory allocation strategy. This strat‐
       egy  can improve run-time performance in programs that meet the follow‐
       ing criteria: Make heavy use of heap memory Call malloc and  free  (and
       realloc)	 infrequently  Allocate	 memory in many small chunks (under 64
       bytes) Reference those chunks very frequently Rarely free those chunks

       In general, the “dense malloc” strategy packs memory more tightly, at a
       slight  cost  of	 execution  speed  of malloc and free, by reducing the
       bookkeeping overhead and round-up padding attached to allocated chunks.
       When  the  processor  loads chunks of memory into its caches, they pack
       more densely and the caches can then be more  effective.	  In  applica‐
       tions  where cache density is a dominant factor in runtime performance,
       this can have a significantly positive net effect.

       To use the “dense malloc” memory allocator,  proceed  as	 follows.   If
       your  program  is  to  be  linked with the -non_shared option, link the
       densemalloc library into your program by adding the following  sequence
       to your cc or ld command-line(s):

       -all -ldensemalloc -none

       If  your program is to be linked with the -call_shared option, you have
       two choices: You can reference the densemalloc library at link time  by
       adding the following sequence to your cc or ld command line(s):

	      -ldensemalloc  You can experiment using densemalloc before link‐
	      ing with that library by executing the following in a shell  and
	      then running the program:


	      For example, for the C Shell:

	      setenv _RLD_LIST ""

	      If  the program's performance is improved, then link with dense‐
	      malloc as described previously.

       The “dense malloc” memory allocator can be  adjusted  with  the	tuning
       variables  described in this section. To use these, define a statically
       initialized variable of the appropriate type with  the  desired	value,
       for example:

       const int __dense_malloc_max_size = 128;

       The  “dense  malloc”  allocator	defaults, limits, and tuning variables
       are: Determines how large a chunk of the address space is reserved  for
       each  pool  (each  size 8, 16, 32, 48 ...). If this space is exhausted,
       another location will be used, but this slows down free().

	      default (taso): 0x600000

	      default (non-taso): 0x1800000 (shown above) Sets the  mmap  hint
	      address  for  where  to  allocate the smallest of the pools; the
	      rest are allocated upward from there.

	      default (taso): 0x0

	      default (non-taso): 0x2F000000000 (shown above)  Determines  the
	      size of the largest request that will be allocated by this allo‐
	      cator. If not a multiple of 16, the value is rounded up  to  the
	      next  multiple  of  16. Requests for memory that are larger than
	      this value are filled by the normal malloc routines.

	      default: 64 bytes

	      limit: 128 bytes Specifies, in pages,  how  large	 an  increment
	      should be obtained on each allocation from the kernel.

	      default: 8 pages

       The  mallopt()  and mallinfo() functions are designed for tuning a spe‐
       cific algorithm. The Tru64 UNIX operating system uses a new, more effi‐
       cient  algorithm.  The  mallopt() and mallinfo() functions are provided
       for System V compatibility only and should not be used by new  applica‐
       tions.  With the exception of the M_KEEP option, the mallopt() function
       has no effect on allocator behavior, and the structure returned by  the
       mallinfo() function might not contain any useful information.

       The  valloc() function is marked as a LEGACY function in the XSH speci‐
       fication and should not be used in new applications.

       Because the alloca() function requires inclusion of <alloca.h> in order
       to work correctly, this function is not portable.

       Use  of	brk(),	sbrk(), mmap(), or other virtual memory primitives can
       interfere with the operation of malloc() and its associated functions.

       Each of the allocation functions returns a pointer  to  space  that  is
       suitably aligned for storage of any type of object. Cast the pointer to
       the type pointer-to-element before using it.

       The malloc(), realloc(), calloc(), and valloc() functions return a null
       pointer	if no memory is available or if the memory arena has been cor‐
       rupted by storing outside the bounds of a block. When this happens, the
       block pointed to by the pointer parameter could be destroyed.

       Upon successful completion, the mallopt() function returns 0 (zero). If
       the argument makes no sense, mallopt() returns -1  and  sets  errno  to
       indicate the error. Otherwise, another nonzero value is returned.

       The  mallinfo()	function  returns  a  pointer to a mallinfo structure,
       defined in the /usr/include/malloc.h header file.

       The malloc(), calloc(), realloc(), and valloc() functions set errno  to
       the specified values for the following conditions:

       Insufficient  storage  space is available.  [Tru64 UNIX]	 For malloc(),
       this value indicates that the value of the size	parameter  is  out  of

	      [Tru64  UNIX]  For realloc(), this value indicates that the buf‐
	      fer is already free.

       The mallopt() function sets errno to the specified values for the  fol‐
       lowing conditions:

       The value argument makes no sense. Conditions that can cause this error
       include: M_MXFAST argument < 0 M_NBLKS argument <= 1  M_GRAIN  argument
       <=  0  All commands after the first small block is allocated An unknown

       Additionally, malloc() and its associated routines call other libc rou‐
       tines, which can set errno (for example, sbrk()).

       Functions: amalloc(3), sysconf(3)

       Standards: standards(5)


List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net