summaryrefslogtreecommitdiffstats
path: root/man/man2/brk.2
diff options
context:
space:
mode:
Diffstat (limited to 'man/man2/brk.2')
-rw-r--r--man/man2/brk.2153
1 files changed, 153 insertions, 0 deletions
diff --git a/man/man2/brk.2 b/man/man2/brk.2
new file mode 100644
index 0000000..309dce2
--- /dev/null
+++ b/man/man2/brk.2
@@ -0,0 +1,153 @@
+.\" 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
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+brk, sbrk \- change data segment size
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "int brk(void *" addr );
+.BI "void *sbrk(intptr_t " increment );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.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 glibc 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.
+.P
+.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)).
+.P
+.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 .
+.P
+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 STANDARDS
+None.
+.SH HISTORY
+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.
+.P
+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.
+.P
+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)