mirror of https://github.com/mkerrisk/man-pages
168 lines
4.9 KiB
Groff
168 lines
4.9 KiB
Groff
.\" 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)
|