1.\" $NetBSD: malloc.3,v 1.38 2010/05/03 08:23:20 jruoho Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93 35.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $ 36.\" 37.Dd May 3, 2010 38.Dt MALLOC 3 39.Os 40.Sh NAME 41.Nm malloc , calloc , realloc , free 42.Nd general purpose memory allocation functions 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft void * 48.Fn malloc "size_t size" 49.Ft void * 50.Fn calloc "size_t number" "size_t size" 51.Ft void * 52.Fn realloc "void *ptr" "size_t size" 53.Ft void 54.Fn free "void *ptr" 55.Sh DESCRIPTION 56The 57.Fn malloc 58function allocates 59.Fa size 60bytes of uninitialized memory. 61The allocated space is suitably aligned (after possible pointer coercion) 62for storage of any type of object. 63.Pp 64The 65.Fn calloc 66function allocates space for 67.Fa number 68objects, 69each 70.Fa size 71bytes in length. 72The result is identical to calling 73.Fn malloc 74with an argument of 75.Dq "number * size" , 76with the exception that the allocated memory is explicitly initialized 77to zero bytes. 78.Pp 79The 80.Fn realloc 81function changes the size of the previously allocated memory referenced by 82.Fa ptr 83to 84.Fa size 85bytes. 86The contents of the memory are unchanged up to the lesser of the new and 87old sizes. 88If the new size is larger, 89the value of the newly allocated portion of the memory is undefined. 90Upon success, the memory referenced by 91.Fa ptr 92is freed and a pointer to the newly allocated memory is returned. 93Note that 94.Fn realloc 95may move the memory allocation, resulting in a different return value than 96.Fa ptr . 97If 98.Fa ptr 99is 100.Dv NULL , 101the 102.Fn realloc 103function behaves identically to 104.Fn malloc 105for the specified size. 106.Pp 107The 108.Fn free 109function causes the allocated memory referenced by 110.Fa ptr 111to be made available for future allocations. 112If 113.Fa ptr 114is 115.Dv NULL , 116no action occurs. 117.Sh RETURN VALUES 118The 119.Fn malloc 120and 121.Fn calloc 122functions return a pointer to the allocated memory if successful; otherwise 123a 124.Dv NULL 125pointer is returned and 126.Va errno 127is set to 128.Er ENOMEM . 129.Pp 130The 131.Fn realloc 132function returns a pointer, possibly identical to 133.Fa ptr , 134to the allocated memory 135if successful; otherwise a 136.Dv NULL 137pointer is returned, and 138.Va errno 139is set to 140.Er ENOMEM 141if the error was the result of an allocation failure. 142The 143.Fn realloc 144function always leaves the original buffer intact 145when an error occurs. 146.Pp 147The 148.Fn free 149function returns no value. 150.Sh EXAMPLES 151When using 152.Fn malloc , 153be careful to avoid the following idiom: 154.Bd -literal -offset indent 155if ((p = malloc(number * size)) == NULL) 156 err(EXIT_FAILURE, "malloc"); 157.Ed 158.Pp 159The multiplication may lead to an integer overflow. 160To avoid this, 161.Fn calloc 162is recommended. 163.Pp 164If 165.Fn malloc 166must be used, be sure to test for overflow: 167.Bd -literal -offset indent 168if (size && number > SIZE_MAX / size) { 169 errno = EOVERFLOW; 170 err(EXIT_FAILURE, "allocation"); 171} 172.Ed 173.Pp 174When using 175.Fn realloc , 176one must be careful to avoid the following idiom: 177.Pp 178.Bd -literal -offset indent 179nsize += 50; 180 181if ((p = realloc(p, nsize)) == NULL) 182 return NULL; 183.Ed 184.Pp 185Do not adjust the variable describing how much memory has been allocated 186until it is known that the allocation has been successful. 187This can cause aberrant program behavior if the incorrect size value is used. 188In most cases, the above example will also leak memory. 189As stated earlier, a return value of 190.Dv NULL 191indicates that the old object still remains allocated. 192Better code looks like this: 193.Bd -literal -offset indent 194newsize = size + 50; 195 196if ((p2 = realloc(p, newsize)) == NULL) { 197 198 if (p != NULL) 199 free(p); 200 201 p = NULL; 202 return NULL; 203} 204 205p = p2; 206size = newsize; 207.Ed 208.Sh SEE ALSO 209.\" .Xr limits 1 , 210.Xr madvise 2 , 211.Xr mmap 2 , 212.Xr sbrk 2 , 213.Xr alloca 3 , 214.Xr atexit 3 , 215.Xr getpagesize 3 , 216.Xr memory 3 , 217.Xr posix_memalign 3 218.Pp 219For the implementation details, see 220.Xr jemalloc 3 . 221.Sh STANDARDS 222The 223.Fn malloc , 224.Fn calloc , 225.Fn realloc 226and 227.Fn free 228functions conform to 229.St -isoC . 230