diff options
Diffstat (limited to 'man/man2/brk.2')
| -rw-r--r-- | man/man2/brk.2 | 153 |
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) |