1.\" $NetBSD: brk.2,v 1.39 2019/09/07 19:32:11 wiz Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)brk.2 8.4 (Berkeley) 5/1/95 31.\" 32.Dd September 7, 2019 33.Dt BRK 2 34.Os 35.Sh NAME 36.Nm brk , 37.Nm sbrk 38.Nd change data segment size 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Ft int 44.Fn brk "void *addr" 45.Ft void * 46.Fn sbrk "intptr_t incr" 47.Sh DESCRIPTION 48.Bf -symbolic 49The 50.Fn brk 51and 52.Fn sbrk 53functions are legacy interfaces from before the 54advent of modern virtual memory management. 55.Fn brk 56is subject to removal and 57.Fn sbrk 58is destined for full compat, where the 59system call will exist in the kernel, but no longer be exposed. 60.Ef 61.Pp 62The 63.Fn brk 64and 65.Fn sbrk 66functions are used to change the amount of memory allocated in a 67process's data segment. 68They do this by moving the address at which the process's heap ends. 69This address is known as the 70.Dq break . 71.Pp 72The 73.Fn brk 74function sets the break to 75.Fa addr . 76.Pp 77The 78.Fn sbrk 79function changes the break by 80.Fa incr 81bytes. 82If 83.Fa incr 84is positive, this allocates 85.Fa incr 86bytes of new memory in the data segment. 87If 88.Fa incr 89is negative, 90this releases the corresponding number of bytes. 91.Pp 92While the break may be set to any address, actual allocation takes 93place in page-sized quantities. 94For allocation and access control purposes the address of the break is 95always rounded up to the next page boundary. 96Thus, changes to the break that do not cross a page boundary have no 97material effect. 98Any new pages that are allocated, however, always appear freshly 99zeroed. 100.Pp 101The 102.Xr getrlimit 2 103system call may be used to determine 104the maximum permissible size of the 105.Em data 106segment; 107it will not be possible to set the break so that the sum of the heap 108size and the data segment is greater than the 109.Dv RLIMIT_DATA 110.Em rlim_max 111value returned from a call to 112.Xr getrlimit 2 . 113One can use the 114.Dq _etext 115symbol to find the end of the program text and thus the beginning of 116the data segment. 117.\" XXX is that always true? there are platforms where there's a fairly 118.\" large unmapped gap between text and data, plus using etext doesn't 119.\" take into account read-only data, which is probably (or should be) 120.\" billed against text size and not data size. 121See 122.Xr end 3 123regarding 124.Dq _etext . 125.Pp 126Historically and in 127.Nx 128the heap immediately follows the data segment, and in fact is 129considered part of it. 130Thus the initial break is the first address after the end of the 131process's uninitialized data (also known as the 132.Dq BSS ) . 133This address is provided by the linker as 134.Dq _end ; 135see 136.Xr end 3 . 137.Pp 138There exist implementations in the wild where this is not the case, 139however, or where the initial break is rounded up to a page boundary, 140or other minor variations, so the recommended more-portable way to 141retrieve the initial break is by calling 142.Fn sbrk 0 143at program startup. 144(This returns the current break without changing it.) 145.Pp 146In any event, the break may not be set to an address below its initial 147position. 148.Pp 149Note that ordinary application code should use 150.Xr malloc 3 151and related functions to allocate memory, or 152.Xr mmap 2 153for lower-level page-granularity control. 154While the 155.Fn brk 156and/or 157.Fn sbrk 158functions exist in most Unix-like environments, their semantics 159sometimes vary subtly and their use is not particularly portable. 160Also, one must take care not to mix calls to 161.Xr malloc 3 162or related functions with calls to 163.Fn brk 164or 165.Fn sbrk 166as this will ordinarily confuse 167.Xr malloc 3 ; 168this can be difficult to accomplish given that many things in the 169C library call 170.Xr malloc 3 171themselves. 172.Sh RETURN VALUES 173.Fn brk 174returns 0 if successful; 175otherwise \-1 with 176.Va errno 177set to indicate why the allocation failed. 178.Pp 179The 180.Fn sbrk 181function returns the prior break value if successful; 182otherwise ((void *)\-1) is returned and 183.Va errno 184is set to indicate why the allocation failed. 185.Sh ERRORS 186.Fn brk 187or 188.Fn sbrk 189will fail and no additional memory will be allocated if 190one of the following are true: 191.Bl -tag -width Er 192.It Bq Er ENOMEM 193The limit, as set by 194.Xr setrlimit 2 , 195was exceeded; 196or the maximum possible size of a data segment (compiled into the 197system) was exceeded; 198or insufficient space existed in the swap area 199to support the expansion. 200.El 201.Sh SEE ALSO 202.Xr execve 2 , 203.Xr getrlimit 2 , 204.Xr mmap 2 , 205.Xr end 3 , 206.Xr free 3 , 207.Xr malloc 3 , 208.Xr sysconf 3 209.Sh HISTORY 210An 211.Fn sbrk 212function call appeared in 213.At v4 . 214A 215.Fn brk 216function call appeared in 217.At v6 . 218.Sh BUGS 219Setting the break may fail due to a temporary lack of swap space. 220It is not possible to distinguish this from a failure caused by 221exceeding the maximum size of the data segment without consulting 222.Xr getrlimit 2 . 223