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

  man pages->Tru64 Unix man pages -> free (3)              
Title
Content
Arch
Section
 

malloc(3)

Contents


NAME    [Toc]    [Back]

       alloca,  calloc, free, mallinfo, malloc, mallopt, realloc,
       valloc - Provide a memory allocator

SYNOPSIS    [Toc]    [Back]

       #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 compatibility:

       #include <malloc.h>

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

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

       [Tru64 UNIX]  Dense Malloc Library (libdensemalloc)

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards 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.

PARAMETERS    [Toc]    [Back]

       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.





DESCRIPTION    [Toc]    [Back]

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

                                  Note

       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() function 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 initialized 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 undefined.


                                  Note

       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 exits.

       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 application. 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 structure.

   Tuning Memory Allocation    [Toc]    [Back]
                                  Note

       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 optimize 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  feature  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 singlethreaded
 applications.  A value  of  2  turns  this
              feature on for both single and multithreaded applications.
  A value of 0 (zero)  turns  this  feature
              off.  All other values cause undefined behavior. It
              is recommended 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  memory  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 making 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  memory
              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
              number 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 integral 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  variable
              __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 __minshrink and  greater  than  __minshrinkfactor
 * heap_size_in_bytes.

              This variable has no effect unless __noshrink is 0.
              The variable __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  *
              heap_size_in_bytes.

              This variable has no effect unless __noshrink is 0.
              The variable __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.
              Permissible 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 memory.

              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 variable 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.

                                    Caution

              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. Permissible values for __small_buff  are  0
              and 1.

              If the process is using a great many small (1 to 15
              byte) buffers, 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 pointers
              returned by malloc and realloc are  bounds  checked
              and  the  ENOMEM  error  is returned if the pointer
              exceeds MAXINT.

   Using the densemalloc Library    [Toc]    [Back]
       The densemalloc library provides an alternate set of  malloc
  routines that implement a "dense malloc" memory allocation
 strategy. This strategy can improve  run-time  performance
  in  programs  that  meet the following 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
       applications  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  linking  with that library by executing the
              following in a shell and then running the program:

              _RLD_LIST="libdensemalloc.so:DEFAULT"

              For example, for the C Shell:

              setenv _RLD_LIST "libdensemalloc.so:DEFAULT"

              If the program's performance is improved, then link
              with densemalloc 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 allocator. 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

NOTES    [Toc]    [Back]

       The  mallopt()  and  mallinfo() functions are designed for
       tuning a specific algorithm. The Tru64 UNIX operating system
  uses  a  new, more efficient algorithm. The mallopt()
       and mallinfo() functions are provided for System V compatibility
  only  and should not be used by new applications.
       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 specification and should not be used in new applications.

RESTRICTIONS    [Toc]    [Back]

       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.

RETURN VALUES    [Toc]    [Back]

       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 corrupted  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.

ERRORS    [Toc]    [Back]

       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 range.

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

       The mallopt() function sets errno to the specified  values
       for the following 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 command

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

SEE ALSO    [Toc]    [Back]

      
      
       Functions: amalloc(3), sysconf(3)

       Standards: standards(5)



                                                        malloc(3)
[ Back ]
 Similar pages
Name OS Title
alloca OpenBSD memory allocator
alloca FreeBSD memory allocator
alloca Linux memory allocator
alloca NetBSD memory allocator
afree Tru64 arena memory allocator
adelete Tru64 arena memory allocator
acreate Tru64 arena memory allocator
acalloc Tru64 arena memory allocator
MALLOC NetBSD kernel memory allocator
malloc NetBSD kernel memory allocator
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service