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