malloc(S)

malloc, free, realloc, calloc, cfree, mallinfo, mallopt -- allocate main memory

Syntax

cc . . . -lc

#include <stdlib.h>

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, elsize;

void cfree(p, num, size)
char *p;
unsigned num, size;

#include <malloc.h>

struct mallinfo mallinfo ()

cc . . . -lmalloc

#include <stdlib.h>

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

Description

malloc- allocate space for an object

free- deallocate space

realloc- change the size of a memory object

calloc- allocate unused space for an array

cfree- deallocate space

mallopt- control the space allocation algorithm

mallinfo- report allocated space usage

There are two versions of the malloc package. The version found in the libmalloc.a archive includes the mallopt( ) routine for backward compatibility. If size is 0 (zero), the two versions of malloc(S) also have different return values.

The routine malloc(S) provides a general-purpose memory allocation package. It allocates space for an object whose size in bytes is specified by size and whose value is indeterminate. This routine allocates the first contiguous reach of free space found in a circular search from the last block allocated or freed, coalescing adjacent blocks as it searches. malloc calls sbrk to get more memory from the system when there is no suitable space already free.

The free function causes the space pointed to by ptr to be deallocated so that it is made available for further allocation; however, its contents are left undisturbed. If ptr is null, no action occurs. Undefined results occur if space assigned by malloc is overrun or if some random number is handed to free.

The cfree routine is provided for compliance to the iBCSe2 standard and simply calls free. The num and size arguments to cfree are not used.

The realloc function changes the size of the memory object pointed to by ptr to the size specified by size. The contents of the object are unchanged up to the lesser of the new and old sizes.

The calloc function allocates unused space for an array of nelem elements each of whose size in bytes is elsize. The space is initialized to 0.

The routine mallopt( ) is provided for backward compatibility. It always returns 0 and does nothing else.

mallinfo returns a structure that provides information about allocation. The mallinfo structure is returned:

   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;  /* space penalty if keep option    */
                          /* is used                         */
   };

This structure is defined in the <malloc.h> header file.

Here is an example program code segment for the mallinfo function:

   #include <stdio.h>
   #include <malloc.h>
   
   main()
   {
   char *cp;
   struct mallinfo minfo;
   

   if ((cp = malloc(1024)) == NULL) {
   

           perror("malloc");
           exit(1);
           }
   minfo = mallinfo();
   printf("%d %d %d\n", minfo.arena, minfo.ordblks, minfo.uordblks);
   }

Return values

malloc, realloc, and calloc return a pointer to the allocated space upon successful completion. mallinfo returns a structure that provides information about allocation. mallopt always returns 0.

malloc, realloc, and calloc return a null pointer (0) if there is no available memory or if the area is corrupted by storing data outside a block boundary. When realloc returns 0, the block pointed to by ptr is left intact.

The libc.a version of malloc returns a non-zero pointer when size is 0. The libmalloc.a version of malloc returns a null pointer when size is 0.

Diagnostics

If these functions fail, errno is set to:

[ENOMEM]: Insufficient memory is available.

Notes

As noted, malloc calls sbrk to allocate memory. Since sbrk takes a signed integer as its argument, malloc fails if an attempt is made to allocate more memory than a signed integer holds (2Gb -1).

Search time increases when many objects have been allocated; that is, if a program allocates but never frees, then each successive allocation takes longer.

The sbrk(S) routine has been withdrawn from XPG3.

History

In previous releases, the malloc package found in libc.a was different from the malloc package found in libmalloc.a. In this release, these two packages found in both archives are almost the same, except that

the two versions of malloc( ) return differently when size is 0;
mallinfo( ) can only be found in libc.a; and
mallopt( ) can only be found in libmalloc.a.

Standards conformance

malloc, free, realloc, and calloc are conformant with:

X/Open Portability Guide, Issue 3, 1989 ;
ANSI X3.159-1989 Programming Language -- C ;
Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2) ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .

The cfree routine conforms to:

Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2) .

The malloc.h header file has been withdrawn from XPG3.

The mallinfo and mallopt routines are not part of any currently supported standard; they were developed by UNIX System Laboratories, Inc. and are maintained by The SCO Group.