Debian Codegraph @

upstream/debian-unstable/man2/brk.2

raw
1 .\" Copyright 2006-2008, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH brk 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 brk, sbrk \- change data segment size
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <unistd.h>
15 .P
16 .BI "int brk(void *" addr );
17 .BI "void *sbrk(intptr_t " increment );
18 .fi
19 .P
20 .RS -4
21 Feature Test Macro Requirements for glibc (see
22 .BR feature_test_macros (7)):
23 .RE
24 .P
25 .BR brk (),
26 .BR sbrk ():
27 .nf
28 Since glibc 2.19:
29 _DEFAULT_SOURCE
30 || ((_XOPEN_SOURCE >= 500) &&
31 ! (_POSIX_C_SOURCE >= 200112L))
32 .\" (_XOPEN_SOURCE >= 500 ||
33 .\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
34 From glibc 2.12 to glibc 2.19:
35 _BSD_SOURCE || _SVID_SOURCE
36 || ((_XOPEN_SOURCE >= 500) &&
37 ! (_POSIX_C_SOURCE >= 200112L))
38 .\" (_XOPEN_SOURCE >= 500 ||
39 .\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
40 Before glibc 2.12:
41 _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500
42 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
43 .fi
44 .SH DESCRIPTION
45 .BR brk ()
46 and
47 .BR sbrk ()
48 change the location of the
49 .IR "program break" ,
50 which defines the end of the process's data segment
51 (i.e., the program break is the first location after the end of the
52 uninitialized data segment).
53 Increasing the program break has the effect of
54 allocating memory to the process;
55 decreasing the break deallocates memory.
56 .P
57 .BR brk ()
58 sets the end of the data segment to the value specified by
59 .IR addr ,
60 when that value is reasonable, the system has enough memory,
61 and the process does not exceed its maximum data size (see
62 .BR setrlimit (2)).
63 .P
64 .BR sbrk ()
65 increments the program's data space by
66 .I increment
67 bytes.
68 Calling
69 .BR sbrk ()
70 with an
71 .I increment
72 of 0 can be used to find the current location of the program break.
73 .SH RETURN VALUE
74 On success,
75 .BR brk ()
76 returns zero.
77 On error, \-1 is returned, and
78 .I errno
79 is set to
80 .BR ENOMEM .
81 .P
82 On success,
83 .BR sbrk ()
84 returns the previous program break.
85 (If the break was increased,
86 then this value is a pointer to the start of the newly allocated memory).
87 On error,
88 .I "(void\ *)\ \-1"
89 is returned, and
90 .I errno
91 is set to
92 .BR ENOMEM .
93 .SH STANDARDS
94 None.
95 .SH HISTORY
96 4.3BSD;
97 SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001.
98 .\"
99 .\" .BR brk ()
100 .\" and
101 .\" .BR sbrk ()
102 .\" are not defined in the C Standard and are deliberately excluded from the
103 .\" POSIX.1-1990 standard (see paragraphs B.1.1.1.3 and B.8.3.3).
104 .SH NOTES
105 Avoid using
106 .BR brk ()
107 and
108 .BR sbrk ():
109 the
110 .BR malloc (3)
111 memory allocation package is the
112 portable and comfortable way of allocating memory.
113 .P
114 Various systems use various types for the argument of
115 .BR sbrk ().
116 Common are
117 .IR int ,
118 .IR ssize_t ,
119 .IR ptrdiff_t ,
120 .IR intptr_t .
121 .\" One sees
122 .\" \f[I]int\f[] (e.g., XPGv4, DU 4.0, HP-UX 11, FreeBSD 4.0, OpenBSD 3.2),
123 .\" \f[I]ssize_t\f[] (OSF1 2.0, Irix 5.3, 6.5),
124 .\" \f[I]ptrdiff_t\f[] (libc4, libc5, ulibc, glibc 2.0, 2.1),
125 .\" \f[I]intptr_t\f[] (e.g., XPGv5, AIX, SunOS 5.8, 5.9, FreeBSD 4.7, NetBSD 1.6,
126 .\" Tru64 5.1, glibc2.2).
127 .SS C library/kernel differences
128 The return value described above for
129 .BR brk ()
130 is the behavior provided by the glibc wrapper function for the Linux
131 .BR brk ()
132 system call.
133 (On most other implementations,
134 the return value from
135 .BR brk ()
136 is the same;
137 this return value was also specified in SUSv2.)
138 However,
139 the actual Linux system call returns the new program break on success.
140 On failure, the system call returns the current break.
141 The glibc wrapper function does some work
142 (i.e., checks whether the new break is less than
143 .IR addr )
144 to provide the 0 and \-1 return values described above.
145 .P
146 On Linux,
147 .BR sbrk ()
148 is implemented as a library function that uses the
149 .BR brk ()
150 system call, and does some internal bookkeeping so that it can
151 return the old break value.
152 .SH SEE ALSO
153 .BR execve (2),
154 .BR getrlimit (2),
155 .BR end (3),
156 .BR malloc (3)