malloc(S) 6 January 1993 malloc(S) Name malloc, free, realloc, calloc, cfree - allocates 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; SVID Syntax char *malloc (size) size_t size; char *realloc (ptr, size) void *ptr; size_t size; char *calloc (nelem, elsize) size_t nelem, elsize; void cfree (p, num, size) char *p; unsigned num, size; Description This is the first of two malloc(S) manual pages. This manual page describes the version found in the libc.a archive, and the next malloc manual page describes the libmalloc.a version. This version of malloc provides a general-purpose memory allocation pack- age. 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. allocates space for an object whose size in bytes is specified by size and whose value is indeterminate. 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 zero. Errors These functions fail if errno is set to: [ENOMEM] Insufficient memory is available. Diagnostics 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. 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. See also brkctl(S), malloc(S), sbrk(S) Standards conformance malloc, free, realloc, and calloc are conformant with: X/Open Portability Guide, Issue 3, 1989; and Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2). The cfree routine conforms to: Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2). malloc(S) 6 January 1993 malloc(S) Name malloc, free, realloc, calloc, mallopt, mallinfo - allocates main memory quickly Syntax cc . . . -lmalloc #include <malloc.h> void *malloc (size) unsigned size; void free (ptr) char *ptr; void *realloc (ptr, size) void *ptr; unsigned size; char *calloc (nelem, elsize) unsigned nelem, elsize; int mallopt (cmd, value) int cmd, value; struct mallinfo mallinfo () SVID Syntax char *malloc (size) unsigned size; char *realloc (ptr, size) void *ptr; unsigned size; Description There are two versions of the malloc(S) package. This is the library version which provides a simple general-purpose memory allocation pack- age, that runs considerably faster than the other malloc(S) package. Both versions are documented in these malloc(S) manual pages; the description of the standard default package starts on page 1. This malloc(S) package is found in the library ``malloc'' and is loaded when the option -lmalloc is used with cc(CP) or ld(CP). malloc 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 mal- loc; after free is performed this space is made available for further allocation, and its contents destroyed (see mallopt below for a way to change this behavior). Undefined results occur if the space assigned by malloc is overrun or if some random number is handed to free. realloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the (possibly moved) block. The contents are unchanged up to the lesser of the new and old sizes. calloc allocates space for an array of nelem elements of size elsize. The space is initialized to zeros. mallopt provides control over the allocation algorithm. The available values for cmd are: MGRAIN 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 allow alignment of any data type. value is rounded up to a multiple of the default when grain is set. MKEEP Preserve data in a freed block until the next malloc, realloc, or calloc. This option is provided only for com- patibility with the old version of malloc and is not recommended. MMXFAST 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 0. MNLBLKS 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. These values are defined in the <malloc.h> header file. mallopt may be called repeatedly, but may not be called after the first small block is allocated. 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 *malloc(), *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); } Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Diagnostics malloc, realloc and calloc 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 mallopt is called after any allocation or if cmd or value are invalid, non-zero is returned. Otherwise, it returns zero. Warnings This package usually uses more data space than the other malloc(S). The code size is also bigger than the other malloc(S). Note that unlike the other malloc(S), this package does not preserve the contents of a block when it is freed, unless the MKEEP option of mallopt is used. Undocumented features of the other malloc(S) have not been duplicated. These routines must be linked with the -lmalloc linker option. See also brkctl(S), malloc(S), sbrk(S) Standards conformance calloc, free, malloc and realloc conform to: AT&T SVID Issue 2; 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. mallinfo and mallopt conform to: AT&T SVID Issue 2, but have been withdrawn from XPG3. The malloc.h header file has been withdrawn from XPG3.