Debian Codegraph @

upstream/debian-trixie/man2/brk.2

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