Manual Pages for UNIX Operating System command usage for man mallopt

Memory Allocation Library Functions               malloc(3MALLOC)



NAME
     malloc, free, memalign, realloc,  valloc,  calloc,  mallopt,
     mallinfo - memory allocator

SYNOPSIS
     cc [ flag ... ] file ... -lmalloc [ library ... ]
     #include 

     void *malloc(size_t size);


     void free(void *ptr);


     void *memalign(size_t alignment, size_t size);


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


     void *valloc(size_t size);


     void *calloc(size_t nelem, size_t elsize);


     #include 

     int mallopt(int cmd, int value);


     struct mallinfo mallinfo(void);


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


     The malloc() function returns a pointer to  a  block  of  at
     least size bytes suitably aligned for any use.


     The argument to free() is a pointer to  a  block  previously
     allocated by malloc(). After free() is performed, this space
     is made available for further allocation, and  its  contents
     have been destroyed. See mallopt() below for a way to change
     this behavior. If ptr is a null pointer, no action occurs.


     Undefined results occur if the space assigned by malloc() is
     overrun or if some random number is handed to free().



SunOS 5.11          Last change: 11 May 2005                    1






Memory Allocation Library Functions               malloc(3MALLOC)



     The free() function does not set errno.


     The memalign() function 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. The value of alignment must
     be a power of two and must be greater than or equal  to  the
     size of a word.


     The realloc() function changes the size of the block pointed
     to by ptr to size bytes and returns a pointer to the (possi-
     bly moved) block. The contents will be unchanged up  to  the
     lesser  of  the  new  and  old sizes. If the new size of the
     block requires movement of the block, the space for the pre-
     vious  instantiation  of the block is freed. If the new size
     is larger, the contents of the newly  allocated  portion  of
     the block are unspecified. If ptr is NULL, realloc() behaves
     like malloc() for the specified size. If size is 0  and  ptr
     is not a null pointer, the space pointed to is freed.


     The valloc() function  has  the  same  effect  as  malloc(),
     except that the allocated memory will be aligned to a multi-
     ple of the value returned by sysconf(_SC_PAGESIZE).


     The calloc() function allocates space for an array of  nelem
     elements of size elsize. The space is initialized to zeros.


     The mallopt() function provides for control over the alloca-
     tion algorithm. The available values for cmd are:

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


     M_NLBLKS    Set  numlblks  to  value.  The  above  mentioned
                 ``large  groups''  each contain numlblks blocks.
                 numlblks must be greater  than  0.  The  default
                 value for numlblks is 100.


     M_GRAIN     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 0. The default value
                 of grain is the smallest number  of  bytes  that



SunOS 5.11          Last change: 11 May 2005                    2






Memory Allocation Library Functions               malloc(3MALLOC)



                 will  allow  alignment  of  any data type. Value
                 will be rounded up to a multiple of the  default
                 when grain is set.


     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 it is not recommended.



     These values are defined in the  header.


     The mallopt() function can be called repeatedly, but  cannot
     be called after the first small block is allocated.


     The mallinfo() function provides instrumentation  describing
     space usage. It returns the mallinfo structure with the fol-
     lowing members:

       unsigned long arena;      /* total space in arena */
       unsigned long ordblks;    /* number of ordinary blocks */
       unsigned long smblks;     /* number of small blocks */
       unsigned long hblkhd;     /* space in holding block headers */
       unsigned long hblks;      /* number of holding blocks */
       unsigned long usmblks;    /* space in small blocks in use */
       unsigned long fsmblks;    /* space in free small blocks */
       unsigned long uordblks;   /* space in ordinary blocks in use */
       unsigned long fordblks;   /* space in free ordinary blocks */
       unsigned long keepcost;   /* space penalty if keep option */
                                 /* is used */



     The mallinfo structure is defined in the  header.


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

RETURN VALUES
     The malloc(), memalign(), realloc(), valloc(), and  calloc()
     functions  return  a  null  pointer  if  there is not enough
     available memory. When realloc()  returns  NULL,  the  block
     pointed  to by ptr is left intact. If size, nelem, or elsize
     is 0, either a null pointer or a unique pointer that can  be
     passed  to  free() is returned. If mallopt() is called after
     any allocation or if cmd or value are  invalid,  a  non-zero



SunOS 5.11          Last change: 11 May 2005                    3






Memory Allocation Library Functions               malloc(3MALLOC)



     value is returned. Otherwise, it returns 0.

ERRORS
     If malloc(), calloc(), or realloc() returns  unsuccessfully,
     errno is set to indicate the error:

     ENOMEM    size bytes of memory exceeds the  physical  limits
               of your system, and cannot be allocated.


     EAGAIN    There is not enough memory available at this point
               in  time to allocate size bytes of memory; but the
               application could try again later.


USAGE
     Unlike malloc(3C), this package does not preserve  the  con-
     tents of a block when it is freed, unless  the M_KEEP option
     of mallopt() is used.


     Undocumented features of  malloc(3C) have  not  been  dupli-
     cated.


     Function prototypes for malloc(), realloc(),  calloc(),  and
     free()  are also defined in the  header for compa-
     tibility with old  applications.  New  applications   should
     include   to access the prototypes for these func-
     tions.


     Comparative features of the various allocation libraries can
     be found in the umem_alloc(3MALLOC) manual page.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     brk(2), bsdmalloc(3MALLOC),  libmtmalloc(3LIB),  malloc(3C),
     mapmalloc(3MALLOC),  mtmalloc(3MALLOC), umem_alloc(3MALLOC),
     watchmalloc(3MALLOC), attributes(5)



SunOS 5.11          Last change: 11 May 2005                    4