unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

MALLOC(3V)                                                          MALLOC(3V)



NAME
       malloc, free, realloc, calloc, cfree, memalign, valloc, mallocmap, mal-
       lopt, mallinfo, malloc_debug, malloc_verify, alloca - memory allocator

SYNOPSIS
       #include <&lt;malloc.h>&gt;

       char *malloc(size)
       unsigned size;

       int free(ptr)
       char *ptr;

       char *realloc(ptr, size)
       char *ptr;
       unsigned size;

       char *calloc(nelem, elsize)
       unsigned nelem, elsize;

       int cfree(ptr)
       char *ptr;

       char *memalign(alignment, size)
       unsigned alignment;
       unsigned size;

       char *valloc(size)
       unsigned size;

       void mallocmap()

       int mallopt(cmd, value)
       int cmd, value;

       struct mallinfo mallinfo()

       #include <&lt;alloca.h>&gt;

       char *alloca(size)
       int size;

SYSTEM V SYNOPSIS
       #include <&lt;malloc.h>&gt;

       void *malloc(size)
       size_t size;

       void free(ptr)
       void *ptr;

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

       void *calloc(nelem, elsize)
       size_t nelem;
       size_t elsize;

       void *memalign(alignment, size)
       size_t alignment;
       size_t size;

       void *valloc(size)
       size_t size;

       The XPG2 versions of the functions listed in this section are  declared
       as they are in SYNOPSIS above, except free(), which is declared as:

       void free(ptr)
       char *ptr;

DESCRIPTION
       These  routines  provide  a  general-purpose memory allocation package.
       They maintain a table of free blocks for efficient allocation and  coa-
       lescing of free storage.  When there is no suitable space already free,
       the allocation routines call sbrk() (see brk(2))  to  get  more  memory
       from the system.

       Each  of  the  allocation  routines returns a pointer to space suitably
       aligned for storage of any type of object.  Each returns a NULL pointer
       if the request cannot be completed (see DIAGNOSTICS).

       malloc()  returns a pointer to a block of at least size bytes, which is
       appropriately aligned.

       free() releases a  previously  allocated  block.   Its  argument  is  a
       pointer  to  a  block previously allocated by malloc(), calloc(), real-
       loc(), malloc(), or memalign().

       realloc() changes the size of the block referenced 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.  If  unable  to
       honor a reallocation request, realloc() leaves its first argument unal-
       tered.  For backwards compatibility, realloc() accepts a pointer  to  a
       block  freed  since  the  most recent call to malloc(), calloc(), real-
       loc(), valloc(), or memalign().  Note: using  realloc()  with  a  block
       freed  before  the  most  recent call to malloc(), calloc(), realloc(),
       valloc(), or memalign() is an error.

       calloc() uses malloc() to allocate space for an array of nelem elements
       of  size  elsize, initializes the space to zeros, and returns a pointer
       to the initialized block.  The  block  can  be  freed  with  free()  or
       cfree().

       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 alignment.  Note: the
       value of alignment must be a power of two, and must be greater than  or
       equal to the size of a word.

       valloc(size) is equivalent to memalign(getpagesize(), size).

       mallocmap()  prints  a  map  of  the heap to the standard output.  mal-
       locmap() prints each block's address, size (in bytes) and status  (free
       or  busy).  A block must have a size that is no larger than the current
       extent of the heap.

       mallopt() allows quick allocation of small blocks of memory.  mallopt()
       tells  subsequent calls to malloc() to allocate holding blocks contain-
       ing small blocks.  Under this small block algorithm, a request to  mal-
       loc()  for a small block of memory returns a pointer to one of the pre-
       allocated small blocks.  Different holding blocks are created as needed
       for different sizes of small blocks.

       cmd may be one of the following values, defined in <&lt;malloc.h>&gt;:

       M_MXFAST       Set the maximum size of blocks to be allocated using the
                      small block algorithm (maxfast) to value.  The algorithm
                      allocates  all  blocks  smaller  than  maxfast  in large
                      groups and then doles them out very quickly.  Initially,
                      maxfast is 0 and the small block algorithm is disabled.

       M_NLBLKS       Set the number of small blocks in a holding block (numl-
                      blks) to value.  The holding blocks each  contain  numl-
                      blks  blocks.   numlblks  must  be  greater than 1.  The
                      default value for numlblks is 100.

       M_GRAIN        Set the granularity for small block requests (grain)  to
                      value.  The sizes of all blocks smaller than maxfast are
                      rounded up to the nearest multiple of grain.  grain must
                      be  greater  than  0.  The default value of grain is the
                      smallest number of bytes which will allow  alignment  of
                      any  data  type.  When grain is set, value is rounded up
                      to a multiple of this default.

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

       mallopt()  may  be  called  repeatedly, but may not be called after the
       first small block is allocated.

       mallinfo() can be used during program development to determine the best
       settings  for  the parameters set by mallopt().  Do not call mallinfo()
       until after  a  call  to  malloc().   mallinfo()  provides  information
       describing  space  usage.   It returns a mallinfo structure, defined in
       <&lt;malloc.h>&gt; as:

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

                     int mxfast;    /* max size of small blocks */
                     int nlblks;    /* number of small blocks in a holding block */
                     int grain;     /* small block rounding factor */
                     int uordbytes; /* space (including overhead) allocated in ord. blks */
                     int allocated; /* number of ordinary blocks allocated */
                     int treeoverhead;   /* bytes used in maintaining the free tree */
              };

       alloca() allocates size bytes of space in the stack frame of the  call-
       er, and returns a pointer to the allocated block.  This temporary space
       is automatically freed when the caller returns.  Note that if the allo-
       cated  block  is beyond the current stack limit, the resulting behavior
       is undefined.

       malloc(), realloc(), memalign() and valloc() return a non-NULL  pointer
       if  size  is  0,  and  calloc()  returns a non-NULL pointer if nelem or
       elsize is 0, but these pointers should not be dereferenced.

       Note: Always cast the value returned by malloc(), realloc(),  calloc(),
       memalign(), valloc() or alloca().

SYSTEM V DESCRIPTION
       The  XPG2  versions  of  malloc(),  realloc(),  memalign() and valloc()
       return NULL if size is 0.  The XPG2 version of calloc() returns NULL if
       nelem or elsize is 0.

RETURN VALUES
       On  success,  malloc(),  calloc(),  realloc(), memalign(), valloc() and
       alloca() return a pointer to space suitably aligned for storage of  any
       type of object.  On failure, they return NULL.

       free() and cfree() return:

       1      on success.

       0      on failure and set errno to indicate the error.

       mallopt() returns 0 on success.  If mallopt() is called after the allo-
       cation of a small block, or if cmd or value is invalid,  it  returns  a
       non-zero value.

       mallinfo() returns a struct mallinfo.

SYSTEM V RETURN VALUES
       If  size is 0, the XPG2 versions of malloc(), realloc(), memalign() and
       valloc() return NULL.

       If nelem or elsize is 0, the XPG2 version of calloc() returns NULL.

       free() does not return a value.

ERRORS
       malloc(),  calloc(),  realloc(),  valloc(),  memalign(),  cfree(),  and
       free() will each fail if one or more of the following are true:

       EINVAL         An invalid argument was specified.

                      The value of ptr passed to free(), cfree(), or realloc()
                      was not a pointer to a  block  previously  allocated  by
                      malloc(), calloc(), realloc(), valloc(), or memalign().

                      The  allocation  heap  is  found to have been corrupted.
                      More detailed information may be  obtained  by  enabling
                      range checks using malloc_debug().

       ENOMEM         size bytes of memory could not be allocated.

FILES
       /usr/lib/debug/malloc.o  diagnostic versions of malloc() routines.
       /usr/lib/debug/mallocmap.o
                                routines to print a map of the heap.

SEE ALSO
       csh(1), ld(1), brk(2), getrlimit(2), sigvec(2), sigstack(2)

       Stephenson, C.J., Fast Fits, in Proceedings of the ACM 9th Symposium on
       Operating Systems, SIGOPS Operating Systems Review,  vol.  17,  no.  5,
       October 1983.
       Core Wars, in Scientific American, May 1984.

DIAGNOSTICS
       More  detailed diagnostics can be made available to programs using mal-
       loc(), calloc(), realloc(), valloc(), memalign(), cfree(), and  free(),
       by  including  a  special  relocatable  object  file  at link time (see
       FILES).  This file also provides routines for control of error handling
       and  diagnosis, as defined below.  Note: these routines are not defined
       in the standard library.

              int malloc_debug(level)
              int level;

              int malloc_verify()

       malloc_debug() sets the level of error diagnosis and  reporting  during
       subsequent  calls  to  malloc(),  calloc(),  realloc(), valloc(), mema-
       lign(), cfree(), and free().  The value of level is interpreted as fol-
       lows:

       Level 0             malloc(),   calloc(),  realloc(),  valloc(),  mema-
                           lign(), cfree(), and free() behave the same  as  in
                           the standard library.

       Level 1             The  routines  abort with a message to the standard
                           error if errors are detected in arguments or in the
                           heap.   If  a bad block is encountered, its address
                           and size are included in the message.

       Level 2             Same as level 1, except that  the  entire  heap  is
                           examined on every call to the above routines.

       malloc_debug()  returns  the  previous  error  diagnostic  level.   The
       default level is 1.

       malloc_verify() attempts to determine if the heap has  been  corrupted.
       It  scans  all blocks in the heap (both free and allocated) looking for
       strange addresses or absurd sizes, and also checks for  inconsistencies
       in  the free space table.  malloc_verify() returns 1 if all checks pass
       without error, and otherwise returns 0.  The checks can take a signifi-
       cant amount of time, so it should not be used indiscriminately.

WARNINGS
       alloca()  is  machine-,  compiler-,  and most of all, system-dependent.
       Its  use  is  strongly  discouraged.   See   getrlimit(2),   sigvec(2),
       sigstack(2), csh(1), and ld(1).

NOTES
       Because  malloc(), realloc(), memalign() and valloc() return a non-NULL
       pointer if size is 0, and calloc() returns a non-NULL pointer if  nelem
       or elsize is 0, a zero size need not be treated as a special case if it
       should be passed to these functions unpredictably.  Also,  the  pointer
       returned  by these functions may be passed to subsequent invocations of
       realloc().

SYSTEM V NOTES
       The XPG2 versions of the allocation routines return NULL when passed  a
       zero size (see SYSTEM V DESCRIPTION above).

BUGS
       Since  realloc() accepts a pointer to a block freed since the last call
       to malloc(), calloc(), realloc(), valloc(), or memalign(),  a  degrada-
       tion of performance results.  The semantics of free() should be changed
       so that the contents of a previously freed block are undefined.



                                24 January 1990                     MALLOC(3V)