-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
-.\" Copyright (c) 1993 Michael Haardt
-.\" (michael@moria.de),
+.\" 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
.\" 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, write to the Free
-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" 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 2003-11-01 "Linux 2.4" "Linux Programmer's Manual"
+.TH BRK 2 2016-03-15 "Linux" "Linux Programmer's Manual"
.SH NAME
brk, sbrk \- change data segment size
.SH SYNOPSIS
.B #include <unistd.h>
-.sp
-.BI "int brk(void *" end_data_segment );
-.sp
+.PP
+.BI "int brk(void *" addr );
+.PP
.BI "void *sbrk(intptr_t " increment );
+.PP
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.PP
+.BR brk (),
+.BR sbrk ():
+.ad l
+.RS 4
+.PD 0
+.TP 4
+Since glibc 2.19:
+.nf
+_DEFAULT_SOURCE ||
+ (_XOPEN_SOURCE\ >=\ 500) &&
+.\" (_XOPEN_SOURCE\ >=\ 500 ||
+.\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
+ ! (_POSIX_C_SOURCE\ >=\ 200112L)
+.fi
+.TP 4
+From glibc 2.12 to 2.19:
+.nf
+_BSD_SOURCE || _SVID_SOURCE ||
+ (_XOPEN_SOURCE\ >=\ 500) &&
+.\" (_XOPEN_SOURCE\ >=\ 500 ||
+.\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
+ ! (_POSIX_C_SOURCE\ >=\ 200112L)
+.fi
+.TP 4
+Before glibc 2.12:
+_BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500
+.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+.PD
+.RE
+.ad b
.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 end_data_segment ,
-when that value is reasonable, the system does have enough memory
-and the process does not exceed its max data size (see
+.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.
-.BR sbrk ()
-isn't a system call, it is just a C library wrapper.
Calling
.BR sbrk ()
-with an increment of 0 can be used to find the current
-location of the program break.
-.SH "RETURN VALUE"
+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.
.I errno
is set to
.BR ENOMEM .
-(But see LINUX NOTES below.)
-
+.PP
On success,
.BR sbrk ()
-returns a pointer to the start of the new area.
-On error, \-1 is returned, and
+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"
+.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 ()
-are not defined in the C Standard and are deliberately excluded from the
-POSIX.1 standard (see paragraphs B.1.1.1.3 and B.8.3.3).
-.SH NOTES
-Various systems use various types for the parameter of
+.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),
+.\" \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,
+.\" \fIintptr_t\fP (e.g., XPGv5, AIX, SunOS 5.8, 5.9, FreeBSD 4.7, NetBSD 1.6,
.\" Tru64 5.1, glibc2.2).
-.SH LINUX NOTES
+.SS C library/kernel differences
The return value described above for
.BR brk ()
-is the behaviour provided by the glibc wrapper function for the Linux
+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.)
+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
-(thus for example, the call
-.I brk(0)
-can be used to obtain the current break).
-The glibc wrapper function does some work to provide the 0
-and \-1 return values described above.
-
+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"
+.SH SEE ALSO
.BR execve (2),
.BR getrlimit (2),
+.BR end (3),
.BR malloc (3)