man2/brk.2

   1 .\" Copyright (c) 1993 Michael Haardt, (michael@moria.de)
   2 .\" and Copyright 2006, 2008, Michael Kerrisk <tmk.manpages@gmail.com>
   3 .\" Fri Apr  2 11:32:09 MET DST 1993
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .\" Modified Wed Jul 21 19:52:58 1993 by Rik Faith <faith@cs.unc.edu>
   8 .\" Modified Sun Aug 21 17:40:38 1994 by Rik Faith <faith@cs.unc.edu>
   9 .\"
  10 .TH BRK 2 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  11 .SH NAME
  12 brk, sbrk \- change data segment size
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <unistd.h>
  19 .PP
  20 .BI "int brk(void *" addr );
  21 .BI "void *sbrk(intptr_t " increment );
  22 .fi
  23 .PP
  24 .RS -4
  25 Feature Test Macro Requirements for glibc (see
  26 .BR feature_test_macros (7)):
  27 .RE
  28 .PP
  29 .BR brk (),
  30 .BR sbrk ():
  31 .nf
  32     Since glibc 2.19:
  33         _DEFAULT_SOURCE
  34             || ((_XOPEN_SOURCE >= 500) &&
  35                 ! (_POSIX_C_SOURCE >= 200112L))
  36 .\"    (_XOPEN_SOURCE >= 500 ||
  37 .\"        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
  38     From glibc 2.12 to 2.19:
  39         _BSD_SOURCE || _SVID_SOURCE
  40             || ((_XOPEN_SOURCE >= 500) &&
  41                 ! (_POSIX_C_SOURCE >= 200112L))
  42 .\"    (_XOPEN_SOURCE >= 500 ||
  43 .\"        _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) &&
  44     Before glibc 2.12:
  45         _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500
  46 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  47 .fi
  48 .SH DESCRIPTION
  49 .BR brk ()
  50 and
  51 .BR sbrk ()
  52 change the location of the
  53 .IR "program break" ,
  54 which defines the end of the process's data segment
  55 (i.e., the program break is the first location after the end of the
  56 uninitialized data segment).
  57 Increasing the program break has the effect of
  58 allocating memory to the process;
  59 decreasing the break deallocates memory.
  60 .PP
  61 .BR brk ()
  62 sets the end of the data segment to the value specified by
  63 .IR addr ,
  64 when that value is reasonable, the system has enough memory,
  65 and the process does not exceed its maximum data size (see
  66 .BR setrlimit (2)).
  67 .PP
  68 .BR sbrk ()
  69 increments the program's data space by
  70 .I increment
  71 bytes.
  72 Calling
  73 .BR sbrk ()
  74 with an
  75 .I increment
  76 of 0 can be used to find the current location of the program break.
  77 .SH RETURN VALUE
  78 On success,
  79 .BR brk ()
  80 returns zero.
  81 On error, \-1 is returned, and
  82 .I errno
  83 is set to
  84 .BR ENOMEM .
  85 .PP
  86 On success,
  87 .BR sbrk ()
  88 returns the previous program break.
  89 (If the break was increased,
  90 then this value is a pointer to the start of the newly allocated memory).
  91 On error,
  92 .I "(void\ *)\ \-1"
  93 is returned, and
  94 .I errno
  95 is set to
  96 .BR ENOMEM .
  97 .SH STANDARDS
  98 4.3BSD; SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001.
  99 .\"
 100 .\" .BR brk ()
 101 .\" and
 102 .\" .BR sbrk ()
 103 .\" are not defined in the C Standard and are deliberately excluded from the
 104 .\" POSIX.1-1990 standard (see paragraphs B.1.1.1.3 and B.8.3.3).
 105 .SH NOTES
 106 Avoid using
 107 .BR brk ()
 108 and
 109 .BR sbrk ():
 110 the
 111 .BR malloc (3)
 112 memory allocation package is the
 113 portable and comfortable way of allocating memory.
 114 .PP
 115 Various systems use various types for the argument of
 116 .BR sbrk ().
 117 Common are \fIint\fP, \fIssize_t\fP, \fIptrdiff_t\fP, \fIintptr_t\fP.
 118 .\" One sees
 119 .\" \fIint\fP (e.g., XPGv4, DU 4.0, HP-UX 11, FreeBSD 4.0, OpenBSD 3.2),
 120 .\" \fIssize_t\fP (OSF1 2.0, Irix 5.3, 6.5),
 121 .\" \fIptrdiff_t\fP (libc4, libc5, ulibc, glibc 2.0, 2.1),
 122 .\" \fIintptr_t\fP (e.g., XPGv5, AIX, SunOS 5.8, 5.9, FreeBSD 4.7, NetBSD 1.6,
 123 .\" Tru64 5.1, glibc2.2).
 124 .SS C library/kernel differences
 125 The return value described above for
 126 .BR brk ()
 127 is the behavior provided by the glibc wrapper function for the Linux
 128 .BR brk ()
 129 system call.
 130 (On most other implementations, the return value from
 131 .BR brk ()
 132 is the same; this return value was also specified in SUSv2.)
 133 However,
 134 the actual Linux system call returns the new program break on success.
 135 On failure, the system call returns the current break.
 136 The glibc wrapper function does some work
 137 (i.e., checks whether the new break is less than
 138 .IR addr )
 139 to provide the 0 and \-1 return values described above.
 140 .PP
 141 On Linux,
 142 .BR sbrk ()
 143 is implemented as a library function that uses the
 144 .BR brk ()
 145 system call, and does some internal bookkeeping so that it can
 146 return the old break value.
 147 .SH SEE ALSO
 148 .BR execve (2),
 149 .BR getrlimit (2),
 150 .BR end (3),
 151 .BR malloc (3)