xref: /freebsd/lib/libsys/brk.2 (revision 8269e7673cf033aba67dab8264fe719920c70f87)
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