1.\" 2.\" Copyright (c) 1980, 1991, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" the American National Standards Committee X3, on Information 7.\" Processing Systems. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $OpenBSD: malloc.3,v 1.137 2023/07/01 18:35:14 otto Exp $ 34.\" 35.Dd $Mdocdate: July 1 2023 $ 36.Dt MALLOC 3 37.Os 38.Sh NAME 39.Nm malloc , 40.Nm calloc , 41.Nm realloc , 42.Nm free , 43.Nm reallocarray , 44.Nm recallocarray , 45.Nm freezero , 46.Nm aligned_alloc , 47.Nm malloc_conceal , 48.Nm calloc_conceal 49.Nd memory allocation and deallocation 50.Sh SYNOPSIS 51.In stdlib.h 52.Ft void * 53.Fn malloc "size_t size" 54.Ft void * 55.Fn calloc "size_t nmemb" "size_t size" 56.Ft void * 57.Fn realloc "void *ptr" "size_t size" 58.Ft void 59.Fn free "void *ptr" 60.Ft void * 61.Fn reallocarray "void *ptr" "size_t nmemb" "size_t size" 62.Ft void * 63.Fn recallocarray "void *ptr" "size_t oldnmemb" "size_t nmemb" "size_t size" 64.Ft void 65.Fn freezero "void *ptr" "size_t size" 66.Ft void * 67.Fn aligned_alloc "size_t alignment" "size_t size" 68.Ft void * 69.Fn malloc_conceal "size_t size" 70.Ft void * 71.Fn calloc_conceal "size_t nmemb" "size_t size" 72.Vt char *malloc_options ; 73.Sh DESCRIPTION 74The standard functions 75.Fn malloc , 76.Fn calloc , 77and 78.Fn realloc 79allocate 80.Em objects , 81regions of memory to store values. 82The 83.Fn malloc 84function allocates uninitialized space for an object of 85the specified 86.Fa size . 87.Fn malloc 88maintains multiple lists of free objects according to size, allocating 89from the appropriate list or requesting memory from the kernel. 90The allocated space is suitably aligned (after possible pointer coercion) for 91storage of any type of object. 92.Pp 93The 94.Fn calloc 95function allocates space for an array of 96.Fa nmemb 97objects, each of the specified 98.Fa size . 99The space is initialized to zero. 100.Pp 101The 102.Fn realloc 103function changes the size of the object pointed to by 104.Fa ptr 105to 106.Fa size 107bytes and returns a pointer to the (possibly moved) object. 108If 109.Fa ptr 110is not 111.Dv NULL , 112it must be a pointer returned by an earlier call to an allocation or 113reallocation function that was not freed in between. 114The contents of the object are unchanged up to the lesser 115of the new and old sizes. 116If the new size is larger, the value of the newly allocated portion 117of the object is indeterminate and uninitialized. 118If the space cannot be allocated, the object 119pointed to by 120.Fa ptr 121is unchanged. 122If 123.Fa ptr 124is 125.Dv NULL , 126.Fn realloc 127behaves like 128.Fn malloc 129and allocates a new object. 130.Pp 131The 132.Fn free 133function causes the space pointed to by 134.Fa ptr 135to be either placed on a list of free blocks to make it available for future 136allocation or, when appropriate, to be returned to the kernel using 137.Xr munmap 2 . 138If 139.Fa ptr 140is 141.Dv NULL , 142no action occurs. 143If 144.Fa ptr 145was previously freed by 146.Fn free 147or a reallocation function, 148the behavior is undefined and the double free is a security concern. 149.Pp 150Designed for safe allocation of arrays, 151the 152.Fn reallocarray 153function is similar to 154.Fn realloc 155except it operates on 156.Fa nmemb 157members of size 158.Fa size 159and checks for integer overflow in the calculation 160.Fa nmemb 161* 162.Fa size . 163.Pp 164Used for the allocation of memory holding sensitive data, 165the 166.Fn recallocarray 167and 168.Fn freezero 169functions guarantee that memory becoming unallocated is explicitly 170.Em discarded , 171meaning pages of memory are disposed via 172.Xr munmap 2 173and cached free objects are cleared with 174.Xr explicit_bzero 3 . 175.Pp 176The 177.Fn recallocarray 178function is similar to 179.Fn reallocarray 180except it ensures newly allocated memory is cleared similar to 181.Fn calloc . 182If 183.Fa ptr 184is 185.Dv NULL , 186.Fa oldnmemb 187is ignored and the call is equivalent to 188.Fn calloc . 189If 190.Fa ptr 191is not 192.Dv NULL , 193.Fa oldnmemb 194must be a value such that 195.Fa oldnmemb 196* 197.Fa size 198is the size of the earlier allocation that returned 199.Fa ptr , 200otherwise the behavior is undefined. 201.Pp 202The 203.Fn freezero 204function is similar to the 205.Fn free 206function except it ensures memory is explicitly discarded. 207If 208.Fa ptr 209is 210.Dv NULL , 211no action occurs. 212If 213.Fa ptr 214is not 215.Dv NULL , 216the 217.Fa size 218argument must be equal to or smaller than the size of the earlier allocation 219that returned 220.Fa ptr . 221.Fn freezero 222guarantees the memory range starting at 223.Fa ptr 224with length 225.Fa size 226is discarded while deallocating the whole object originally allocated. 227.Pp 228The 229.Fn aligned_alloc 230function allocates 231.Fa size 232bytes of memory such that the allocation's base address is a multiple of 233.Fa alignment . 234The requested 235.Fa alignment 236must be a power of 2. 237If 238.Fa size 239is not a multiple of 240.Fa alignment , 241behavior is undefined. 242.Pp 243The 244.Fn malloc_conceal 245and 246.Fn calloc_conceal 247functions behave the same as 248.Fn malloc 249and 250.Fn calloc 251respectively, 252with the exception that the allocation returned is marked with the 253.Dv MAP_CONCEAL 254.Xr mmap 2 255flag and calling 256.Fn free 257on the allocation will discard the contents explicitly. 258A reallocation of a concealed allocation will leave these properties intact. 259.Sh MALLOC OPTIONS 260Upon the first call to the 261.Fn malloc 262family of functions, an initialization sequence inspects the 263value of the 264.Va vm.malloc_conf 265.Xr sysctl 2 , 266next checks the environment for a variable called 267.Ev MALLOC_OPTIONS , 268and finally looks at the global variable 269.Va malloc_options 270in the program. 271Each is scanned for the flags documented below. 272Unless otherwise noted uppercase means on, lowercase means off. 273During initialization, flags occurring later modify the behaviour 274that was requested by flags processed earlier. 275.Bl -tag -width indent 276.It Cm C 277.Dq Canaries . 278Add canaries at the end of allocations in order to detect 279heap overflows. 280The canary's content is checked when 281.Nm free 282is called. 283If it has been corrupted, the process is aborted. 284.It Cm D 285.Dq Dump . 286.Fn malloc 287will dump a leak report using 288.Xr utrace 2 289at exit. 290To record the dump: 291.Pp 292.Dl $ MALLOC_OPTIONS=D ktrace -tu program ... 293.Pp 294To view the leak report: 295.Pp 296.Dl $ kdump -u malloc ... 297.Pp 298By default, the immediate caller of a 299.Nm 300function will be recorded. 301Use malloc options 302.Cm 2 303or 304.Cm 3 305to record the caller one or two stack frames deeper instead. 306These malloc options imply 307.Cm D . 308.It Cm F 309.Dq Freecheck . 310Enable more extensive double free and use after free detection. 311All chunks in the delayed free list will be checked for double frees and 312write after frees. 313Unused pages on the freelist are read and write protected to 314cause a segmentation fault upon access. 315.It Cm G 316.Dq Guard . 317Enable guard pages. 318Each page size or larger allocation is followed by a guard page that will 319cause a segmentation fault upon any access. 320.It Cm J 321.Dq More junking . 322Increase the junk level by one if it is smaller than 2. 323.It Cm j 324.Dq Less junking . 325Decrease the junk level by one if it is larger than 0. 326Junking writes some junk bytes into the area allocated. 327Junk is bytes of 0xdb when allocating; 328small allocations are initially junked with 0xdf as are freed allocations. 329By default the junk level is 1: after free, 330small chunks are completely junked; 331for pages the first part is junked. 332After a delay, 333the filling pattern is validated and the process is aborted if the pattern 334was modified. 335For junk level 2, junking is done on allocation as well and without size 336restrictions. 337If the junk level is zero, no junking is performed. 338.It Cm R 339.Dq realloc . 340Always reallocate when 341.Fn realloc 342is called, even if the initial allocation was big enough. 343.\".Pp 344.\".It Cm U 345.\".Dq utrace . 346.\"Generate entries for 347.\".Xr ktrace 1 348.\"for all operations. 349.\"Consult the source for this one. 350.It Cm S 351.\" Malloc option S is vaguely documented on purpose. 352Enable all options suitable for security auditing. 353.It Cm U 354.Dq Free unmap . 355Enable use after free protection for larger allocations. 356Unused pages on the freelist are read and write protected to 357cause a segmentation fault upon access. 358.It Cm V 359.Dq Verbose . 360Use with 361.Cm D 362to get a verbose dump of malloc's internal state. 363.It Cm X 364.Dq xmalloc . 365Rather than return failure, 366.Xr abort 3 367the program with a diagnostic message on stderr. 368It is the intention that this option be set at compile time by 369including in the source: 370.Bd -literal -offset indent 371extern char *malloc_options; 372malloc_options = "X"; 373.Ed 374.Pp 375Note that this will cause code that is supposed to handle 376out-of-memory conditions gracefully to abort instead. 377.It Cm < 378.Dq Halve the cache size . 379Decrease the size of the free page cache by a factor of two. 380.It Cm > 381.Dq Double the cache size . 382Increase the size of the free page cache by a factor of two. 383.El 384.Pp 385If a program changes behavior if any of these options (except 386.Cm X ) 387are used, 388it is buggy. 389.Pp 390The default size of the cache is 64 single page allocations. 391It also caches a number of larger regions. 392Multi-threaded programs use multiple pools. 393.Sh RETURN VALUES 394Upon successful completion, the allocation functions 395return a pointer to the allocated space; otherwise, 396.Dv NULL 397is returned and 398.Va errno 399is set to 400.Er ENOMEM . 401The function 402.Fn aligned_alloc 403returns 404.Dv NULL 405and sets 406.Va errno 407to 408.Er EINVAL 409if 410.Fa alignment 411is not a power of 2. 412.Pp 413If 414.Fa nmemb 415or 416.Fa size 417is equal to 0, a unique pointer to an access protected, 418zero sized object is returned. 419Access via this pointer will generate a 420.Dv SIGSEGV 421exception. 422.Pp 423If multiplying 424.Fa nmemb 425and 426.Fa size 427results in integer overflow, 428.Fn calloc , 429.Fn reallocarray 430and 431.Fn recallocarray 432return 433.Dv NULL 434and set 435.Va errno 436to 437.Er ENOMEM . 438.Pp 439If 440.Fa ptr 441is not 442.Dv NULL 443and multiplying 444.Fa oldnmemb 445and 446.Fa size 447results in integer overflow, 448.Fn recallocarray 449returns 450.Dv NULL 451and sets 452.Va errno 453to 454.Er EINVAL . 455.Sh IDIOMS 456Consider 457.Fn calloc 458or the extensions 459.Fn reallocarray 460and 461.Fn recallocarray 462when there is multiplication in the 463.Fa size 464argument of 465.Fn malloc 466or 467.Fn realloc . 468For example, avoid this common idiom as it may lead to integer overflow: 469.Bd -literal -offset indent 470if ((p = malloc(num * size)) == NULL) 471 err(1, NULL); 472.Ed 473.Pp 474A drop-in replacement is the 475.Ox 476extension 477.Fn reallocarray : 478.Bd -literal -offset indent 479if ((p = reallocarray(NULL, num, size)) == NULL) 480 err(1, NULL); 481.Ed 482.Pp 483Alternatively, 484.Fn calloc 485may be used at the cost of initialization overhead. 486.Pp 487When using 488.Fn realloc , 489be careful to avoid the following idiom: 490.Bd -literal -offset indent 491size += 50; 492if ((p = realloc(p, size)) == NULL) 493 return (NULL); 494.Ed 495.Pp 496Do not adjust the variable describing how much memory has been allocated 497until the allocation has been successful. 498This can cause aberrant program behavior if the incorrect size value is used. 499In most cases, the above sample will also result in a leak of memory. 500As stated earlier, a return value of 501.Dv NULL 502indicates that the old object still remains allocated. 503Better code looks like this: 504.Bd -literal -offset indent 505newsize = size + 50; 506if ((newp = realloc(p, newsize)) == NULL) { 507 free(p); 508 p = NULL; 509 size = 0; 510 return (NULL); 511} 512p = newp; 513size = newsize; 514.Ed 515.Pp 516As with 517.Fn malloc , 518it is important to ensure the new size value will not overflow; 519i.e. avoid allocations like the following: 520.Bd -literal -offset indent 521if ((newp = realloc(p, num * size)) == NULL) { 522 ... 523.Ed 524.Pp 525Instead, use 526.Fn reallocarray : 527.Bd -literal -offset indent 528if ((newp = reallocarray(p, num, size)) == NULL) { 529 ... 530.Ed 531.Pp 532Calling 533.Fn realloc 534with a 535.Dv NULL 536.Fa ptr 537is equivalent to calling 538.Fn malloc . 539Instead of this idiom: 540.Bd -literal -offset indent 541if (p == NULL) 542 newp = malloc(newsize); 543else 544 newp = realloc(p, newsize); 545.Ed 546.Pp 547Use the following: 548.Bd -literal -offset indent 549newp = realloc(p, newsize); 550.Ed 551.Pp 552The 553.Fn recallocarray 554function should be used for resizing objects containing sensitive data like 555keys. 556To avoid leaking information, 557it guarantees memory is cleared before placing it on the internal free list. 558Deallocation of such an object should be done by calling 559.Fn freezero . 560.Sh ENVIRONMENT 561.Bl -tag -width "MALLOC_OPTIONS" 562.It Ev MALLOC_OPTIONS 563String of option flags. 564.El 565.Sh EXAMPLES 566If 567.Fn malloc 568must be used with multiplication, be sure to test for overflow: 569.Bd -literal -offset indent 570size_t num, size; 571\&... 572 573/* Check for size_t overflow */ 574if (size && num > SIZE_MAX / size) 575 errc(1, EOVERFLOW, "overflow"); 576 577if ((p = malloc(num * size)) == NULL) 578 err(1, NULL); 579.Ed 580.Pp 581The above test is not sufficient in all cases. 582For example, multiplying ints requires a different set of checks: 583.Bd -literal -offset indent 584int num, size; 585\&... 586 587/* Avoid invalid requests */ 588if (size < 0 || num < 0) 589 errc(1, EOVERFLOW, "overflow"); 590 591/* Check for signed int overflow */ 592if (size && num > INT_MAX / size) 593 errc(1, EOVERFLOW, "overflow"); 594 595if ((p = malloc(num * size)) == NULL) 596 err(1, NULL); 597.Ed 598.Pp 599Assuming the implementation checks for integer overflow as 600.Ox 601does, it is much easier to use 602.Fn calloc , 603.Fn reallocarray , 604or 605.Fn recallocarray . 606.Pp 607The above examples could be simplified to: 608.Bd -literal -offset indent 609if ((p = reallocarray(NULL, num, size)) == NULL) 610 err(1, NULL); 611.Ed 612.Pp 613or at the cost of initialization: 614.Bd -literal -offset indent 615if ((p = calloc(num, size)) == NULL) 616 err(1, NULL); 617.Ed 618.Pp 619Set a systemwide reduction of the cache to a quarter of the 620default size and use guard pages: 621.Pp 622.Dl # sysctl vm.malloc_conf='G<<' 623.Sh DIAGNOSTICS 624If any of the functions detect an error condition, 625a message will be printed to file descriptor 6262 (not using stdio). 627Errors will result in the process being aborted. 628.Pp 629Here is a brief description of the error messages and what they mean: 630.Bl -tag -width Ds 631.It Dq out of memory 632If the 633.Cm X 634option is specified, it is an error for the allocation functions 635to return 636.Dv NULL . 637.It Dq bogus pointer (double free?) 638An attempt to 639.Fn free 640or 641reallocate an unallocated pointer was made. 642.It Dq double free 643There was an attempt to free an allocation that had already been freed. 644.It Dq write after free 645An allocation has been modified after it was freed. 646.It Dq modified chunk-pointer 647The pointer passed to 648.Fn free 649or a reallocation function has been modified. 650.It Dq canary corrupted address offset@length 651A byte after the requested size has been overwritten, 652indicating a heap overflow. 653The offset at which corruption was detected is printed before the @, 654and the requested length of the allocation after the @. 655.It Dq recorded size oldsize inconsistent with size 656.Fn recallocarray 657or 658.Fn freezero 659has detected that the given old size does not match the recorded size in its 660meta data. 661Enabling option 662.Cm C 663allows 664.Fn recallocarray 665to catch more of these cases. 666.It Dq recursive call 667An attempt was made to call recursively into these functions, i.e., from a 668signal handler. 669This behavior is not supported. 670In particular, signal handlers should 671.Em not 672use any of the 673.Fn malloc 674functions nor utilize any other functions which may call 675.Fn malloc 676(e.g., 677.Xr stdio 3 678routines). 679.It Dq unknown char in MALLOC_OPTIONS 680We found something we didn't understand. 681.It any other error 682.Fn malloc 683detected an internal error; 684consult sources and/or wizards. 685.El 686.Sh SEE ALSO 687.Xr brk 2 , 688.Xr mmap 2 , 689.Xr munmap 2 , 690.Xr sysctl 2 , 691.Xr alloca 3 , 692.Xr getpagesize 3 , 693.Xr posix_memalign 3 694.Sh STANDARDS 695The 696.Fn malloc , 697.Fn calloc , 698.Fn realloc , 699and 700.Fn free 701functions conform to 702.St -ansiC . 703The 704.Fn aligned_alloc 705function conforms to 706.St -isoC-2011 . 707.Pp 708If 709.Fa nmemb 710or 711.Fa size 712are 0, the return value is implementation defined; 713other conforming implementations may return 714.Dv NULL 715in this case. 716.Pp 717The 718.Ev MALLOC_OPTIONS 719environment variable, the 720.Va vm.malloc_conf 721sysctl and the 722.Sx DIAGNOSTICS 723output are extensions to the standard. 724.Sh HISTORY 725A 726.Fn free 727internal kernel function and a predecessor to 728.Fn malloc , 729.Fn alloc , 730first appeared in 731.At v1 . 732C library functions 733.Fn alloc 734and 735.Fn free 736appeared in 737.At v6 . 738The functions 739.Fn malloc , 740.Fn calloc , 741and 742.Fn realloc 743first appeared in 744.At v7 . 745.Pp 746A new implementation by Chris Kingsley was introduced in 747.Bx 4.2 , 748followed by a complete rewrite by Poul-Henning Kamp which appeared in 749.Fx 2.2 750and was included in 751.Ox 2.0 . 752These implementations were all 753.Xr sbrk 2 754based. 755In 756.Ox 3.8 , 757Thierry Deval rewrote 758.Nm 759to use the 760.Xr mmap 2 761system call, 762making the page addresses returned by 763.Nm 764random. 765A rewrite by Otto Moerbeek introducing a new central data structure and more 766randomization appeared in 767.Ox 4.4 . 768.Pp 769The 770.Fn reallocarray 771function appeared in 772.Ox 5.6 . 773The 774.Fn recallocarray 775function appeared in 776.Ox 6.1 . 777The 778.Fn freezero 779function appeared in 780.Ox 6.2 . 781The 782.Fn aligned_alloc 783function appeared in 784.Ox 6.5 . 785The 786.Fn malloc_conceal 787and 788.Fn calloc_conceal 789functions appeared in 790.Ox 6.6 . 791.Sh CAVEATS 792When using 793.Fn malloc , 794be wary of signed integer and 795.Vt size_t 796overflow especially when there is multiplication in the 797.Fa size 798argument. 799.Pp 800Signed integer overflow will cause undefined behavior which compilers 801typically handle by wrapping back around to negative numbers. 802Depending on the input, this can result in allocating more or less 803memory than intended. 804.Pp 805An unsigned overflow has defined behavior which will wrap back around and 806return less memory than intended. 807.Pp 808A signed or unsigned integer overflow is a 809.Em security 810risk if less memory is returned than intended. 811Subsequent code may corrupt the heap by writing beyond the memory that was 812allocated. 813An attacker may be able to leverage this heap corruption to execute arbitrary 814code. 815.Pp 816Consider using 817.Fn calloc , 818.Fn reallocarray 819or 820.Fn recallocarray 821instead of using multiplication in 822.Fn malloc 823and 824.Fn realloc 825to avoid these problems on 826.Ox . 827.Pp 828The mechanism to record caller functions when using malloc options 829.Cm 2 830or 831.Cm 3 832is not guaranteed to work for all platforms, compilers or compilation 833options, 834and might even crash your program. 835Use 836.Em only 837for debugging purposes. 838