Wrapped long lines, wrapped at sentence boundaries; stripped trailing

[thirdparty/man-pages.git] / man2 / brk.2

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (c) 1993 Michael Haardt
.\" (michael@moria.de),
.\" Fri Apr  2 11:32:09 MET DST 1993
.\"
.\" 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, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\" 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"
.SH NAME
brk, sbrk \- change data segment size
.SH SYNOPSIS
.B #include <unistd.h>
.sp
.BI "int brk(void *" end_data_segment );
.sp
.BI "void *sbrk(intptr_t " increment );
.SH DESCRIPTION
.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
.BR setrlimit (2)).

.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"
On success,
.BR brk ()
returns zero.
On error, \-1 is returned, and
.I errno
is set to
.BR ENOMEM .
(But see LINUX NOTES below.)

On success,
.BR sbrk ()
returns a pointer to the start of the new area.
On error, \-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 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 ().
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, glibc2.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).
.SH LINUX NOTES
The return value described above for
.BR brk ()
is the behaviour 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.)
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 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 malloc (3)