| .\" Copyright (c) 1993 Michael Haardt, (michael@moria.de) |
| .\" and Copyright 2006, 2008, Michael Kerrisk <tmk.manpages@gmail.com> |
| .\" Fri Apr 2 11:32:09 MET DST 1993 |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified Wed Jul 21 19:52:58 1993 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified Sun Aug 21 17:40:38 1994 by Rik Faith <faith@cs.unc.edu> |
| .\" |
| .TH BRK 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| brk, sbrk \- change data segment size |
| .SH SYNOPSIS |
| .nf |
| .B #include <unistd.h> |
| .PP |
| .BI "int brk(void *" addr ); |
| .BI "void *sbrk(intptr_t " increment ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .BR brk (), |
| .BR sbrk (): |
| .nf |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| || ((_XOPEN_SOURCE >= 500) && |
| ! (_POSIX_C_SOURCE >= 200112L)) |
| .\" (_XOPEN_SOURCE >= 500 || |
| .\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) && |
| From glibc 2.12 to 2.19: |
| _BSD_SOURCE || _SVID_SOURCE |
| || ((_XOPEN_SOURCE >= 500) && |
| ! (_POSIX_C_SOURCE >= 200112L)) |
| .\" (_XOPEN_SOURCE >= 500 || |
| .\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) && |
| Before glibc 2.12: |
| _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 |
| .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED |
| .fi |
| .SH DESCRIPTION |
| .BR brk () |
| and |
| .BR sbrk () |
| change the location of the |
| .IR "program break" , |
| which defines the end of the process's data segment |
| (i.e., the program break is the first location after the end of the |
| uninitialized data segment). |
| Increasing the program break has the effect of |
| allocating memory to the process; |
| decreasing the break deallocates memory. |
| .PP |
| .BR brk () |
| sets the end of the data segment to the value specified by |
| .IR addr , |
| when that value is reasonable, the system has enough memory, |
| and the process does not exceed its maximum data size (see |
| .BR setrlimit (2)). |
| .PP |
| .BR sbrk () |
| increments the program's data space by |
| .I increment |
| bytes. |
| Calling |
| .BR sbrk () |
| with an |
| .I increment |
| of 0 can be used to find the current location of the program break. |
| .SH RETURN VALUE |
| On success, |
| .BR brk () |
| returns zero. |
| On error, \-1 is returned, and |
| .I errno |
| is set to |
| .BR ENOMEM . |
| .PP |
| On success, |
| .BR sbrk () |
| returns the previous program break. |
| (If the break was increased, |
| then this value is a pointer to the start of the newly allocated memory). |
| On error, |
| .I "(void\ *)\ \-1" |
| is returned, and |
| .I errno |
| is set to |
| .BR ENOMEM . |
| .SH CONFORMING TO |
| 4.3BSD; SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001. |
| .\" |
| .\" .BR brk () |
| .\" and |
| .\" .BR sbrk () |
| .\" are not defined in the C Standard and are deliberately excluded from the |
| .\" POSIX.1-1990 standard (see paragraphs B.1.1.1.3 and B.8.3.3). |
| .SH NOTES |
| Avoid using |
| .BR brk () |
| and |
| .BR sbrk (): |
| the |
| .BR malloc (3) |
| memory allocation package is the |
| portable and comfortable way of allocating memory. |
| .PP |
| Various systems use various types for the argument of |
| .BR sbrk (). |
| Common are \fIint\fP, \fIssize_t\fP, \fIptrdiff_t\fP, \fIintptr_t\fP. |
| .\" One sees |
| .\" \fIint\fP (e.g., XPGv4, DU 4.0, HP-UX 11, FreeBSD 4.0, OpenBSD 3.2), |
| .\" \fIssize_t\fP (OSF1 2.0, Irix 5.3, 6.5), |
| .\" \fIptrdiff_t\fP (libc4, libc5, ulibc, glibc 2.0, 2.1), |
| .\" \fIintptr_t\fP (e.g., XPGv5, AIX, SunOS 5.8, 5.9, FreeBSD 4.7, NetBSD 1.6, |
| .\" Tru64 5.1, glibc2.2). |
| .SS C library/kernel differences |
| The return value described above for |
| .BR brk () |
| is the behavior provided by the glibc wrapper function for the Linux |
| .BR brk () |
| system call. |
| (On most other implementations, the return value from |
| .BR brk () |
| is the same; this return value was also specified in SUSv2.) |
| However, |
| the actual Linux system call returns the new program break on success. |
| On failure, the system call returns the current break. |
| The glibc wrapper function does some work |
| (i.e., checks whether the new break is less than |
| .IR addr ) |
| to provide the 0 and \-1 return values described above. |
| .PP |
| On Linux, |
| .BR sbrk () |
| is implemented as a library function that uses the |
| .BR brk () |
| system call, and does some internal bookkeeping so that it can |
| return the old break value. |
| .SH SEE ALSO |
| .BR execve (2), |
| .BR getrlimit (2), |
| .BR end (3), |
| .BR malloc (3) |