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.\" @(#)brk.2 8.4 (Berkeley) 5/1/95 29.\" 30.Dd June 2, 2018 31.Dt BRK 2 32.Os 33.Sh NAME 34.Nm brk , 35.Nm sbrk 36.Nd change data segment size 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In unistd.h 41.Ft int 42.Fn brk "const void *addr" 43.Ft void * 44.Fn sbrk "intptr_t incr" 45.Sh DESCRIPTION 46.Bf -symbolic 47The 48.Fn brk 49and 50.Fn sbrk 51functions are legacy interfaces from before the 52advent of modern virtual memory management. 53They are deprecated and not present on the arm64 or riscv architectures. 54The 55.Xr mmap 2 56interface should be used to allocate pages instead. 57.Ef 58.Pp 59The 60.Fn brk 61and 62.Fn sbrk 63functions are used to change the amount of memory allocated in a 64process's data segment. 65They do this by moving the location of the 66.Dq break . 67The break is the first address after the end of the process's 68uninitialized data segment (also known as the 69.Dq BSS ) . 70.Pp 71The 72.Fn brk 73function 74sets the break to 75.Fa addr . 76.Pp 77The 78.Fn sbrk 79function raises the break by 80.Fa incr 81bytes, thus allocating at least 82.Fa incr 83bytes of new memory in the data segment. 84If 85.Fa incr 86is negative, 87the break is lowered by 88.Fa incr 89bytes. 90.Sh NOTES 91While the actual process data segment size maintained by the kernel will only 92grow or shrink in page sizes, these functions allow setting the break 93to unaligned values (i.e., it may point to any address inside the last 94page of the data segment). 95.Pp 96The current value of the program break may be determined by calling 97.Fn sbrk 0 . 98See also 99.Xr end 3 . 100.Pp 101The 102.Xr getrlimit 2 103system call may be used to determine 104the maximum permissible size of the 105data segment. 106It will not be possible to set the break 107beyond 108.Dq Va etext No + Va rlim.rlim_max 109where the 110.Va rlim.rlim_max 111value is returned from a call to 112.Fn getrlimit RLIMIT_DATA &rlim . 113(See 114.Xr end 3 115for the definition of 116.Va etext ) . 117.Sh RETURN VALUES 118.Rv -std brk 119.Pp 120The 121.Fn sbrk 122function returns the prior break value if successful; 123otherwise the value 124.Po Vt "void *" Pc Ns \-1 125is returned and the global variable 126.Va errno 127is set to indicate the error. 128.Sh ERRORS 129The 130.Fn brk 131and 132.Fn sbrk 133functions 134will fail if: 135.Bl -tag -width Er 136.It Bq Er EINVAL 137The requested break value was beyond the beginning of the data segment. 138.It Bq Er ENOMEM 139The data segment size limit, as set by 140.Xr setrlimit 2 , 141was exceeded. 142.It Bq Er ENOMEM 143Insufficient space existed in the swap area 144to support the expansion of the data segment. 145.El 146.Sh SEE ALSO 147.Xr execve 2 , 148.Xr getrlimit 2 , 149.Xr mmap 2 , 150.Xr end 3 , 151.Xr free 3 , 152.Xr malloc 3 153.Sh HISTORY 154The 155.Fn brk 156function appeared in 157.At v7 . 158.Fx 11.0 159introduced the arm64 and riscv architectures which do not support 160.Fn brk 161or 162.Fn sbrk . 163.Sh BUGS 164Mixing 165.Fn brk 166or 167.Fn sbrk 168with 169.Xr malloc 3 , 170.Xr free 3 , 171or similar functions will result in non-portable program behavior. 172.Pp 173Setting the break may fail due to a temporary lack of 174swap space. 175It is not possible to distinguish this 176from a failure caused by exceeding the maximum size of 177the data segment without consulting 178.Xr getrlimit 2 . 179.Pp 180.Fn sbrk 181is sometimes used to monitor heap use by calling with an argument of 0. 182The result is unlikely to reflect actual utilization in combination with an 183.Xr mmap 2 184based malloc. 185.Pp 186.Fn brk 187and 188.Fn sbrk 189are not thread-safe. 190