]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1993 Michael Haardt |
2 | .\" (michael@moria.de), | |
3 | .\" Fri Apr 2 11:32:09 MET DST 1993 | |
4 | .\" | |
1dd72f9c | 5 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
6 | .\" This is free documentation; you can redistribute it and/or |
7 | .\" modify it under the terms of the GNU General Public License as | |
8 | .\" published by the Free Software Foundation; either version 2 of | |
9 | .\" the License, or (at your option) any later version. | |
10 | .\" | |
11 | .\" The GNU General Public License's references to "object code" | |
12 | .\" and "executables" are to be interpreted as the output of any | |
13 | .\" document formatting or typesetting system, including | |
14 | .\" intermediate and printed output. | |
15 | .\" | |
16 | .\" This manual is distributed in the hope that it will be useful, | |
17 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 | .\" GNU General Public License for more details. | |
20 | .\" | |
21 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
22 | .\" License along with this manual; if not, see |
23 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified Wed Jul 21 19:52:58 1993 by Rik Faith <faith@cs.unc.edu> | |
27 | .\" Modified Sun Aug 21 17:40:38 1994 by Rik Faith <faith@cs.unc.edu> | |
28 | .\" | |
5722c835 | 29 | .TH BRK 2 2015-07-23 "Linux" "Linux Programmer's Manual" |
fea681da MK |
30 | .SH NAME |
31 | brk, sbrk \- change data segment size | |
32 | .SH SYNOPSIS | |
33 | .B #include <unistd.h> | |
34 | .sp | |
b5c0095a | 35 | .BI "int brk(void *" addr ); |
fea681da MK |
36 | .sp |
37 | .BI "void *sbrk(intptr_t " increment ); | |
cc4615cc MK |
38 | .sp |
39 | .in -4n | |
40 | Feature Test Macro Requirements for glibc (see | |
41 | .BR feature_test_macros (7)): | |
42 | .in | |
43 | .sp | |
cc4615cc MK |
44 | .BR brk (), |
45 | .BR sbrk (): | |
2df50e3d MK |
46 | .ad l |
47 | .RS 4 | |
48 | .PD 0 | |
49 | .TP 4 | |
eb15868c MK |
50 | Since glibc 2.19: |
51 | .nf | |
52 | _DEFAULT_SOURCE || | |
cf7fa0a1 MK |
53 | (_XOPEN_SOURCE\ >=\ 500) && |
54 | .\" (_XOPEN_SOURCE\ >=\ 500 || | |
55 | .\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) && | |
a446ac0c | 56 | ! (_POSIX_C_SOURCE\ >=\ 200112L) |
eb15868c MK |
57 | .fi |
58 | .TP 4 | |
59 | From glibc 2.12 to 2.19: | |
2df50e3d MK |
60 | .nf |
61 | _BSD_SOURCE || _SVID_SOURCE || | |
cf7fa0a1 MK |
62 | (_XOPEN_SOURCE\ >=\ 500) && |
63 | .\" (_XOPEN_SOURCE\ >=\ 500 || | |
64 | .\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) && | |
e464f054 | 65 | ! (_POSIX_C_SOURCE\ >=\ 200112L) |
2df50e3d | 66 | .fi |
368bbfa9 | 67 | .TP 4 |
2df50e3d | 68 | Before glibc 2.12: |
cf7fa0a1 MK |
69 | _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 |
70 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
2df50e3d MK |
71 | .PD |
72 | .RE | |
cc4615cc | 73 | .ad b |
fea681da | 74 | .SH DESCRIPTION |
b5c0095a MK |
75 | .BR brk () |
76 | and | |
77 | .BR sbrk () | |
78 | change the location of the | |
79 | .IR "program break" , | |
80 | which defines the end of the process's data segment | |
81 | (i.e., the program break is the first location after the end of the | |
82 | uninitialized data segment). | |
83 | Increasing the program break has the effect of | |
84 | allocating memory to the process; | |
85 | decreasing the break deallocates memory. | |
86 | ||
e511ffb6 | 87 | .BR brk () |
fea681da | 88 | sets the end of the data segment to the value specified by |
b5c0095a MK |
89 | .IR addr , |
90 | when that value is reasonable, the system has enough memory, | |
91 | and the process does not exceed its maximum data size (see | |
fea681da MK |
92 | .BR setrlimit (2)). |
93 | ||
e511ffb6 | 94 | .BR sbrk () |
fea681da MK |
95 | increments the program's data space by |
96 | .I increment | |
97 | bytes. | |
fea681da | 98 | Calling |
e511ffb6 | 99 | .BR sbrk () |
b5c0095a MK |
100 | with an |
101 | .I increment | |
102 | of 0 can be used to find the current location of the program break. | |
47297adb | 103 | .SH RETURN VALUE |
fea681da | 104 | On success, |
e511ffb6 | 105 | .BR brk () |
be352a31 MK |
106 | returns zero. |
107 | On error, \-1 is returned, and | |
108 | .I errno | |
109 | is set to | |
110 | .BR ENOMEM . | |
be352a31 MK |
111 | |
112 | On success, | |
e511ffb6 | 113 | .BR sbrk () |
b5c0095a MK |
114 | returns the previous program break. |
115 | (If the break was increased, | |
116 | then this value is a pointer to the start of the newly allocated memory). | |
117 | On error, | |
118 | .I "(void\ *)\ \-1" | |
119 | is returned, and | |
fea681da MK |
120 | .I errno |
121 | is set to | |
122 | .BR ENOMEM . | |
47297adb | 123 | .SH CONFORMING TO |
97c1eac8 | 124 | 4.3BSD; SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001. |
b5c0095a MK |
125 | .\" |
126 | .\" .BR brk () | |
127 | .\" and | |
128 | .\" .BR sbrk () | |
129 | .\" are not defined in the C Standard and are deliberately excluded from the | |
130 | .\" POSIX.1-1990 standard (see paragraphs B.1.1.1.3 and B.8.3.3). | |
131 | .SH NOTES | |
132 | Avoid using | |
ae050d9a | 133 | .BR brk () |
c13182ef | 134 | and |
b5c0095a MK |
135 | .BR sbrk (): |
136 | the | |
137 | .BR malloc (3) | |
138 | memory allocation package is the | |
139 | portable and comfortable way of allocating memory. | |
140 | ||
c4bb193f | 141 | Various systems use various types for the argument of |
fea681da | 142 | .BR sbrk (). |
9ff08aad | 143 | Common are \fIint\fP, \fIssize_t\fP, \fIptrdiff_t\fP, \fIintptr_t\fP. |
fea681da | 144 | .\" One sees |
75b94dc3 | 145 | .\" \fIint\fP (e.g., XPGv4, DU 4.0, HP-UX 11, FreeBSD 4.0, OpenBSD 3.2), |
9ff08aad | 146 | .\" \fIssize_t\fP (OSF1 2.0, Irix 5.3, 6.5), |
6459c9ca | 147 | .\" \fIptrdiff_t\fP (libc4, libc5, ulibc, glibc 2.0, 2.1), |
75b94dc3 | 148 | .\" \fIintptr_t\fP (e.g., XPGv5, AIX, SunOS 5.8, 5.9, FreeBSD 4.7, NetBSD 1.6, |
fea681da | 149 | .\" Tru64 5.1, glibc2.2). |
0722a578 | 150 | .SS C library/kernel differences |
be352a31 MK |
151 | The return value described above for |
152 | .BR brk () | |
d9bfdb9c | 153 | is the behavior provided by the glibc wrapper function for the Linux |
be352a31 | 154 | .BR brk () |
c13182ef MK |
155 | system call. |
156 | (On most other implementations, the return value from | |
157 | .BR brk () | |
b5c0095a | 158 | is the same; this return value was also specified in SUSv2.) |
c13182ef | 159 | However, |
be352a31 | 160 | the actual Linux system call returns the new program break on success. |
b5c0095a MK |
161 | On failure, the system call returns the current break. |
162 | The glibc wrapper function does some work | |
163 | (i.e., checks whether the new break is less than | |