Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


MALLOC(3)                  Library Functions Manual                  MALLOC(3)

NAME
     malloc, calloc, realloc, free - general purpose memory allocation
     functions

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <stdlib.h>

     void *
     malloc(size_t size);

     void *
     calloc(size_t number, size_t size);

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

     void
     free(void *ptr);

DESCRIPTION
     The malloc() function allocates size bytes of uninitialized memory.  The
     allocated space is suitably aligned (after possible pointer coercion) for
     storage of any type of object.

     The calloc() function allocates space for number objects, each size bytes
     in length.  The result is identical to calling malloc() with an argument
     of "number * size", with the exception that the allocated memory is
     explicitly initialized to zero bytes.

     The realloc() function changes the size of the previously allocated
     memory referenced by ptr to size bytes.  The contents of the memory are
     unchanged up to the lesser of the new and old sizes.  If the new size is
     larger, the value of the newly allocated portion of the memory is
     undefined.  Upon success, the memory referenced by ptr is freed and a
     pointer to the newly allocated memory is returned.

     Note that realloc() may move the memory allocation, resulting in a
     different return value than ptr.  If ptr is NULL, the realloc() function
     behaves identically to malloc() for the specified size.

     The free() function causes the allocated memory referenced by ptr to be
     made available for future allocations.  If ptr is NULL, no action occurs.

RETURN VALUES
     The malloc() and calloc() functions return a pointer to the allocated
     memory if successful; otherwise a NULL pointer is returned and errno is
     set to ENOMEM.

     The realloc() function returns a pointer, possibly identical to ptr, to
     the allocated memory if successful; otherwise a NULL pointer is returned,
     and errno is set to ENOMEM if the error was the result of an allocation
     failure.  The realloc() function always leaves the original buffer intact
     when an error occurs.  If size is 0, either NULL or a pointer that can be
     safely passed to free(3) is returned.

     The free() function returns no value.

EXAMPLES
     When using malloc(), be careful to avoid the following idiom:

           if ((p = malloc(number * size)) == NULL)
                   err(EXIT_FAILURE, "malloc");

     The multiplication may lead to an integer overflow.  To avoid this,
     reallocarr(3) is recommended.

     If malloc() must be used, be sure to test for overflow:

           if (size && number > SIZE_MAX / size) {
                   errno = EOVERFLOW;
                   err(EXIT_FAILURE, "allocation");
           }

     The above test is not sufficient in all cases.  For example, multiplying
     ints requires a different set of checks:

           int num, size;
           ...

           /* Avoid invalid requests */
           if (size < 0 || num < 0)
                   errc(1, EOVERFLOW, "overflow");

           /* Check for signed int overflow */
           if (size && num > INT_MAX / size)
                   errc(1, EOVERFLOW, "overflow");

           if ((p = malloc(size * num)) == NULL)
                   err(1, "malloc");

     Assuming the implementation checks for integer overflow as NetBSD does,
     it is much easier to use calloc() or reallocarr(3).

     The above examples could be simplified to:

           ptr = NULL;
           if ((e = reallocarr(&ptr, num, size)))
                   errx(1, "reallocarr", strerror(e));

           or at the cost of initialization:
           if ((p = calloc(num, size)) == NULL)
                   err(1, "calloc");

     When using realloc(), one must be careful to avoid the following idiom:

           nsize += 50;

           if ((p = realloc(p, nsize)) == NULL)
                   return NULL;

     Do not adjust the variable describing how much memory has been allocated
     until it is known that the allocation has been successful.  This can
     cause aberrant program behavior if the incorrect size value is used.  In
     most cases, the above example will also leak memory.  As stated earlier,
     a return value of NULL indicates that the old object still remains
     allocated.  Better code looks like this:

           newsize = size + 50;

           if ((p2 = realloc(p, newsize)) == NULL) {

                   if (p != NULL)
                           free(p);

                   p = NULL;
                   return NULL;
           }

           p = p2;
           size = newsize;

SEE ALSO
     madvise(2), mmap(2), sbrk(2), aligned_alloc(3), alloca(3), atexit(3),
     getpagesize(3), memory(3), posix_memalign(3), reallocarr(3)

     For the implementation details, see jemalloc(3).

STANDARDS
     The malloc(), calloc(), realloc() and free() functions conform to ISO/IEC
     9899:1990 ("ISO C90").

HISTORY
     A free() internal kernel function and a predecessor to malloc(), alloc(),
     first appeared in Version 1 AT&T UNIX.  The C Library functions alloc()
     and free() appeared in Version 6 AT&T UNIX.  The functions malloc(),
     calloc(), and realloc() first appeared in Version 7 AT&T UNIX.

     A new implementation by Chris Kingsley was introduced in 4.2BSD, followed
     by a complete rewrite by Poul-Henning Kamp ("phk's malloc" or "new
     malloc") which appeared in FreeBSD 2.2 and was included in NetBSD 1.5 and
     OpenBSD 2.0.  These implementations were all sbrk(2) based.

     The jemalloc(3) allocator became the default system allocator first in
     FreeBSD 7.0 and then in NetBSD 5.0.

NetBSD 10.99                     June 1, 2016                     NetBSD 10.99