1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd June 2, 2018 29.Dt BRK 2 30.Os 31.Sh NAME 32.Nm brk , 33.Nm sbrk 34.Nd change data segment size 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In unistd.h 39.Ft int 40.Fn brk "const void *addr" 41.Ft void * 42.Fn sbrk "intptr_t incr" 43.Sh DESCRIPTION 44.Bf -symbolic 45The 46.Fn brk 47and 48.Fn sbrk 49functions are legacy interfaces from before the 50advent of modern virtual memory management. 51They are deprecated and not present on the arm64 or riscv architectures. 52The 53.Xr mmap 2 54interface should be used to allocate pages instead. 55.Ef 56.Pp 57The 58.Fn brk 59and 60.Fn sbrk 61functions are used to change the amount of memory allocated in a 62process's data segment. 63They do this by moving the location of the 64.Dq break . 65The break is the first address after the end of the process's 66uninitialized data segment (also known as the 67.Dq BSS ) . 68.Pp 69The 70.Fn brk 71function 72sets the break to 73.Fa addr . 74.Pp 75The 76.Fn sbrk 77function raises the break by 78.Fa incr 79bytes, thus allocating at least 80.Fa incr 81bytes of new memory in the data segment. 82If 83.Fa incr 84is negative, 85the break is lowered by 86.Fa incr 87bytes. 88.Sh NOTES 89While the actual process data segment size maintained by the kernel will only 90grow or shrink in page sizes, these functions allow setting the break 91to unaligned values (i.e., it may point to any address inside the last 92page of the data segment). 93.Pp 94The current value of the program break may be determined by calling 95.Fn sbrk 0 . 96See also 97.Xr end 3 . 98.Pp 99The 100.Xr getrlimit 2 101system call may be used to determine 102the maximum permissible size of the 103data segment. 104It will not be possible to set the break 105beyond 106.Dq Va etext No + Va rlim.rlim_max 107where the 108.Va rlim.rlim_max 109value is returned from a call to 110.Fn getrlimit RLIMIT_DATA &rlim . 111(See 112.Xr end 3 113for the definition of 114.Va etext ) . 115.Sh RETURN VALUES 116.Rv -std brk 117.Pp 118The 119.Fn sbrk 120function returns the prior break value if successful; 121otherwise the value 122.Po Vt "void *" Pc Ns \-1 123is returned and the global variable 124.Va errno 125is set to indicate the error. 126.Sh ERRORS 127The 128.Fn brk 129and 130.Fn sbrk 131functions 132will fail if: 133.Bl -tag -width Er 134.It Bq Er EINVAL 135The requested break value was beyond the beginning of the data segment. 136.It Bq Er ENOMEM 137The data segment size limit, as set by 138.Xr setrlimit 2 , 139was exceeded. 140.It Bq Er ENOMEM 141Insufficient space existed in the swap area 142to support the expansion of the data segment. 143.El 144.Sh SEE ALSO 145.Xr execve 2 , 146.Xr getrlimit 2 , 147.Xr mmap 2 , 148.Xr end 3 , 149.Xr free 3 , 150.Xr malloc 3 151.Sh HISTORY 152The 153.Fn brk 154function appeared in 155.At v7 . 156.Fx 11.0 157introduced the arm64 and riscv architectures which do not support 158.Fn brk 159or 160.Fn sbrk . 161.Sh BUGS 162Mixing 163.Fn brk 164or 165.Fn sbrk 166with 167.Xr malloc 3 , 168.Xr free 3 , 169or similar functions will result in non-portable program behavior. 170.Pp 171Setting the break may fail due to a temporary lack of 172swap space. 173It is not possible to distinguish this 174from a failure caused by exceeding the maximum size of 175the data segment without consulting 176.Xr getrlimit 2 . 177.Pp 178.Fn sbrk 179is sometimes used to monitor heap use by calling with an argument of 0. 180The result is unlikely to reflect actual utilization in combination with an 181.Xr mmap 2 182based malloc. 183.Pp 184.Fn brk 185and 186.Fn sbrk 187are not thread-safe. 188