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. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)brk.2 8.2 (Berkeley) 12/11/93
33.\"
34.Dd December 11, 1993
35.Dt BRK 2
36.Os BSD 4
37.Sh NAME
38.Nm brk ,
39.Nm sbrk
40.Nd change data segment size
41.Sh SYNOPSIS
42.Fd #include <sys/types.h>
43.Ft int
44.Fn brk "const char *addr"
45.Ft char *
46.Fn *sbrk "int incr"
47.Sh DESCRIPTION
48.Bf -symbolic
49The brk and sbrk functions are historical curiosities
50left over from earlier days before the advent of virtual memory management.
51.Ef
52The
53.Fn brk
54function
55sets the break or lowest address
56of a process's data segment (uninitialized data) to
57.Fa addr
58(immediately above bss).
59Data addressing is restricted between
60.Fa addr
61and the lowest stack pointer to the stack segment.
62Memory is allocated by
63.Fa brk
64in page size pieces;
65if
66.Fa addr
67is not evenly divisible by the system page size, it is
68increased to the next page boundary.
69.Pp
70.\" The
71.\" .Nm sbrk
72.\" function
73.\" allocates chunks of
74.\" .Fa incr
75.\" bytes
76.\" to the process's data space
77.\" and returns an address pointer.
78.\" The
79.\" .Xr malloc 3
80.\" function utilizes
81.\" .Nm sbrk .
82.\" .Pp
83The current value of the program break is reliably returned by
84.Dq Li sbrk(0)
85(see also
86.Xr end 3 ) .
87The
88.Xr getrlimit 2
89system call may be used to determine
90the maximum permissible size of the
91.Em data
92segment;
93it will not be possible to set the break
94beyond the
95.Em rlim_max
96value returned from a call to
97.Xr getrlimit 2 ,
98e.g.
99.Dq qetext + rlp\(->rlim_max.
100(see
101.Xr end 3
102for the definition of
103.Em etext ) .
104.Sh RETURN VALUES
105.Fn Brk
106returns 0 if successful;
107otherwise -1 with
108.Va errno
109set to indicate why the allocation failed.
110The
111.Fn sbrk
112function returns a pointer to the base of the new storage if successful;
113otherwise -1 with
114.Va errno
115set to indicate why the allocation failed.
116.Sh ERRORS
117.Fn Sbrk
118will fail and no additional memory will be allocated if
119one of the following are true:
120.Bl -tag -width [ENOMEM]
121.It Bq Er ENOMEM
122The limit, as set by
123.Xr setrlimit 2 ,
124was exceeded.
125.It Bq Er ENOMEM
126The maximum possible size of a data segment (compiled into the
127system) was exceeded.
128.It Bq Er ENOMEM
129Insufficient space existed in the swap area
130to support the expansion.
131.El
132.Sh SEE ALSO
133.Xr execve 2 ,
134.Xr getrlimit 2 ,
135.Xr malloc 3 ,
136.Xr end 3
137.Sh BUGS
138Setting the break may fail due to a temporary lack of
139swap space. It is not possible to distinguish this
140from a failure caused by exceeding the maximum size of
141the data segment without consulting
142.Xr getrlimit 2 .
143.Sh HISTORY
144A
145.Fn brk
146function call appeared in
147.At v7 .
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. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)brk.2 8.2 (Berkeley) 12/11/93
33.\"
34.Dd December 11, 1993
35.Dt BRK 2
36.Os BSD 4
37.Sh NAME
38.Nm brk ,
39.Nm sbrk
40.Nd change data segment size
41.Sh SYNOPSIS
42.Fd #include <sys/types.h>
43.Ft int
44.Fn brk "const char *addr"
45.Ft char *
46.Fn *sbrk "int incr"
47.Sh DESCRIPTION
48.Bf -symbolic
49The brk and sbrk functions are historical curiosities
50left over from earlier days before the advent of virtual memory management.
51.Ef
52The
53.Fn brk
54function
55sets the break or lowest address
56of a process's data segment (uninitialized data) to
57.Fa addr
58(immediately above bss).
59Data addressing is restricted between
60.Fa addr
61and the lowest stack pointer to the stack segment.
62Memory is allocated by
63.Fa brk
64in page size pieces;
65if
66.Fa addr
67is not evenly divisible by the system page size, it is
68increased to the next page boundary.
69.Pp
70.\" The
71.\" .Nm sbrk
72.\" function
73.\" allocates chunks of
74.\" .Fa incr
75.\" bytes
76.\" to the process's data space
77.\" and returns an address pointer.
78.\" The
79.\" .Xr malloc 3
80.\" function utilizes
81.\" .Nm sbrk .
82.\" .Pp
83The current value of the program break is reliably returned by
84.Dq Li sbrk(0)
85(see also
86.Xr end 3 ) .
87The
88.Xr getrlimit 2
89system call may be used to determine
90the maximum permissible size of the
91.Em data
92segment;
93it will not be possible to set the break
94beyond the
95.Em rlim_max
96value returned from a call to
97.Xr getrlimit 2 ,
98e.g.
99.Dq qetext + rlp\(->rlim_max.
100(see
101.Xr end 3
102for the definition of
103.Em etext ) .
104.Sh RETURN VALUES
105.Fn Brk
106returns 0 if successful;
107otherwise -1 with
108.Va errno
109set to indicate why the allocation failed.
110The
111.Fn sbrk
112function returns a pointer to the base of the new storage if successful;
113otherwise -1 with
114.Va errno
115set to indicate why the allocation failed.
116.Sh ERRORS
117.Fn Sbrk
118will fail and no additional memory will be allocated if
119one of the following are true:
120.Bl -tag -width [ENOMEM]
121.It Bq Er ENOMEM
122The limit, as set by
123.Xr setrlimit 2 ,
124was exceeded.
125.It Bq Er ENOMEM
126The maximum possible size of a data segment (compiled into the
127system) was exceeded.
128.It Bq Er ENOMEM
129Insufficient space existed in the swap area
130to support the expansion.
131.El
132.Sh SEE ALSO
133.Xr execve 2 ,
134.Xr getrlimit 2 ,
135.Xr malloc 3 ,
136.Xr end 3
137.Sh BUGS
138Setting the break may fail due to a temporary lack of
139swap space. It is not possible to distinguish this
140from a failure caused by exceeding the maximum size of
141the data segment without consulting
142.Xr getrlimit 2 .
143.Sh HISTORY
144A
145.Fn brk
146function call appeared in
147.At v7 .