xref: /dflybsd-src/lib/libc/sys/sbrk.2 (revision 925dae71dffcc17c2a71c6e2b51aabfd05c37d80)
1*925dae71SSascha Wildner.\" Copyright (c) 1980, 1991, 1993
2*925dae71SSascha Wildner.\"	The Regents of the University of California.  All rights reserved.
3*925dae71SSascha Wildner.\"
4*925dae71SSascha Wildner.\" Redistribution and use in source and binary forms, with or without
5*925dae71SSascha Wildner.\" modification, are permitted provided that the following conditions
6*925dae71SSascha Wildner.\" are met:
7*925dae71SSascha Wildner.\" 1. Redistributions of source code must retain the above copyright
8*925dae71SSascha Wildner.\"    notice, this list of conditions and the following disclaimer.
9*925dae71SSascha Wildner.\" 2. Redistributions in binary form must reproduce the above copyright
10*925dae71SSascha Wildner.\"    notice, this list of conditions and the following disclaimer in the
11*925dae71SSascha Wildner.\"    documentation and/or other materials provided with the distribution.
12*925dae71SSascha Wildner.\" 3. Neither the name of the University nor the names of its contributors
13*925dae71SSascha Wildner.\"    may be used to endorse or promote products derived from this software
14*925dae71SSascha Wildner.\"    without specific prior written permission.
15*925dae71SSascha Wildner.\"
16*925dae71SSascha Wildner.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17*925dae71SSascha Wildner.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18*925dae71SSascha Wildner.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19*925dae71SSascha Wildner.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20*925dae71SSascha Wildner.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21*925dae71SSascha Wildner.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22*925dae71SSascha Wildner.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23*925dae71SSascha Wildner.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24*925dae71SSascha Wildner.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25*925dae71SSascha Wildner.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26*925dae71SSascha Wildner.\" SUCH DAMAGE.
27*925dae71SSascha Wildner.\"
28*925dae71SSascha Wildner.\"     @(#)brk.2	8.4 (Berkeley) 5/1/95
29*925dae71SSascha Wildner.\" $FreeBSD: src/lib/libc/sys/brk.2,v 1.13.2.10 2002/03/04 12:00:31 dwmalone Exp $
30*925dae71SSascha Wildner.\"
31*925dae71SSascha Wildner.Dd March 1, 2019
32*925dae71SSascha Wildner.Dt SBRK 2
33*925dae71SSascha Wildner.Os
34*925dae71SSascha Wildner.Sh NAME
35*925dae71SSascha Wildner.Nm sbrk
36*925dae71SSascha Wildner.Nd change data segment size (obsolete)
37*925dae71SSascha Wildner.Sh LIBRARY
38*925dae71SSascha Wildner.Lb libc
39*925dae71SSascha Wildner.Sh SYNOPSIS
40*925dae71SSascha Wildner.In sys/types.h
41*925dae71SSascha Wildner.In unistd.h
42*925dae71SSascha Wildner.Ft void *
43*925dae71SSascha Wildner.Fn sbrk "intptr_t incr"
44*925dae71SSascha Wildner.Sh DESCRIPTION
45*925dae71SSascha Wildner.Bf -symbolic
46*925dae71SSascha WildnerThe
47*925dae71SSascha Wildner.Fn sbrk
48*925dae71SSascha Wildnerfunction is a legacy interface from before the
49*925dae71SSascha Wildneradvent of modern virtual memory management.
50*925dae71SSascha Wildner.Fn sbrk
51*925dae71SSascha Wildnerhas only limited functionality due to having to play nice with
52*925dae71SSascha Wildnermodern system calls such as
53*925dae71SSascha Wildner.Xr mmap 2 .
54*925dae71SSascha Wildner.Ef
55*925dae71SSascha Wildner.Pp
56*925dae71SSascha WildnerThe
57*925dae71SSascha Wildner.Fn sbrk
58*925dae71SSascha Wildnerfunction is used to change the amount of memory allocated in a
59*925dae71SSascha Wildnerprocess's data segment.
60*925dae71SSascha WildnerIt does this by moving the location of the
61*925dae71SSascha Wildner.Dq break .
62*925dae71SSascha WildnerThe break is the first address after the end of the process's
63*925dae71SSascha Wildneruninitialized data segment (also known as the
64*925dae71SSascha Wildner.Dq BSS ) .
65*925dae71SSascha Wildner.Pp
66*925dae71SSascha WildnerThe break range is limited by the
67*925dae71SSascha Wildner.Dv RLIMIT_DATA
68*925dae71SSascha Wildnerresource limit applied to the process.
69*925dae71SSascha Wildner.Pp
70*925dae71SSascha WildnerThe
71*925dae71SSascha Wildner.Fn sbrk
72*925dae71SSascha Wildnerfunction raises the break by
73*925dae71SSascha Wildner.Fa incr
74*925dae71SSascha Wildnerbytes, returning a pointer to the base of the new memory.
75*925dae71SSascha WildnerAny attempt to lower the break point will return
76*925dae71SSascha Wildner.Po Vt "void *" Pc Ns \-1
77*925dae71SSascha Wildnerand set errno to
78*925dae71SSascha Wildner.Er EOPNOTSUPP .
79*925dae71SSascha Wildner.Sh NOTES
80*925dae71SSascha WildnerWhile the actual process data segment size maintained by the kernel will only
81*925dae71SSascha Wildnergrow or shrink in page sizes, this function allows setting the break
82*925dae71SSascha Wildnerto unaligned values (i.e., it may point to any address inside the last
83*925dae71SSascha Wildnerpage of the data segment).
84*925dae71SSascha Wildner.Pp
85*925dae71SSascha WildnerThe current value of the program break may be determined by calling
86*925dae71SSascha Wildner.Fn sbrk 0 .
87*925dae71SSascha Wildner.Pp
88*925dae71SSascha WildnerThe
89*925dae71SSascha Wildner.Fn sbrk
90*925dae71SSascha Wildnerfunction is thread-safe.
91*925dae71SSascha WildnerSee also
92*925dae71SSascha Wildner.Xr end 3 .
93*925dae71SSascha Wildner.Pp
94*925dae71SSascha WildnerThe
95*925dae71SSascha Wildner.Xr getrlimit 2
96*925dae71SSascha Wildnersystem call may be used to determine
97*925dae71SSascha Wildnerthe maximum permissible size of the
98*925dae71SSascha Wildnerdata segment.
99*925dae71SSascha WildnerIt will not be possible to set the break
100*925dae71SSascha Wildnerbeyond
101*925dae71SSascha Wildner.Dq Va etext No + Va rlim.rlim_max
102*925dae71SSascha Wildnerwhere the
103*925dae71SSascha Wildner.Va rlim.rlim_max
104*925dae71SSascha Wildnervalue is returned from a call to
105*925dae71SSascha Wildner.Fn getrlimit RLIMIT_DATA &rlim .
106*925dae71SSascha Wildner(See
107*925dae71SSascha Wildner.Xr end 3
108*925dae71SSascha Wildnerfor the definition of
109*925dae71SSascha Wildner.Va etext ) .
110*925dae71SSascha Wildner.Sh RETURN VALUES
111*925dae71SSascha WildnerThe
112*925dae71SSascha Wildner.Fn sbrk
113*925dae71SSascha Wildnerfunction returns the prior break pointer if successful;
114*925dae71SSascha Wildnerotherwise the value
115*925dae71SSascha Wildner.Po Vt "void *" Pc Ns \-1
116*925dae71SSascha Wildneris returned and the global variable
117*925dae71SSascha Wildner.Va errno
118*925dae71SSascha Wildneris set to indicate the error.
119*925dae71SSascha Wildner.Sh ERRORS
120*925dae71SSascha Wildner.Fn sbrk
121*925dae71SSascha Wildnerwill fail if:
122*925dae71SSascha Wildner.Bl -tag -width Er
123*925dae71SSascha Wildner.It Bq Er EINVAL
124*925dae71SSascha WildnerThe requested break value was beyond the beginning of the data segment.
125*925dae71SSascha Wildner.It Bq Er ENOMEM
126*925dae71SSascha WildnerThe data segment size limit, as set by
127*925dae71SSascha Wildner.Xr setrlimit 2 ,
128*925dae71SSascha Wildnerwas exceeded.
129*925dae71SSascha Wildner.It Bq Er ENOMEM
130*925dae71SSascha WildnerInsufficient space existed in the swap area
131*925dae71SSascha Wildnerto support the expansion of the data segment.
132*925dae71SSascha Wildner.It Bq Er EOPNOTSUPP
133*925dae71SSascha WildnerAn attempt has been made to perform an action that is no longer supported
134*925dae71SSascha Wildnerby this function.
135*925dae71SSascha Wildner.El
136*925dae71SSascha Wildner.Sh SEE ALSO
137*925dae71SSascha Wildner.Xr execve 2 ,
138*925dae71SSascha Wildner.Xr getrlimit 2 ,
139*925dae71SSascha Wildner.Xr mmap 2 ,
140*925dae71SSascha Wildner.Xr end 3 ,
141*925dae71SSascha Wildner.Xr free 3 ,
142*925dae71SSascha Wildner.Xr malloc 3
143*925dae71SSascha Wildner.Sh BUGS
144*925dae71SSascha WildnerMixing
145*925dae71SSascha Wildner.Fn sbrk
146*925dae71SSascha Wildnerwith
147*925dae71SSascha Wildner.Xr malloc 3 ,
148*925dae71SSascha Wildner.Xr free 3 ,
149*925dae71SSascha Wildneror similar functions will result in non-portable program behavior.
150*925dae71SSascha Wildner.Pp
151*925dae71SSascha WildnerSetting the break may fail due to a temporary lack of
152*925dae71SSascha Wildnerswap space.
153*925dae71SSascha WildnerIt is not possible to distinguish this
154*925dae71SSascha Wildnerfrom a failure caused by exceeding the maximum size of
155*925dae71SSascha Wildnerthe data segment without consulting
156*925dae71SSascha Wildner.Xr getrlimit 2 .
157