lib/libc/sys/brk.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)brk.2       8.4 (Berkeley) 5/1/95
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 24, 2018
  32 .Dt BRK 2
  33 .Os
  34 .Sh NAME
  35 .Nm brk ,
  36 .Nm sbrk
  37 .Nd change data segment size
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In unistd.h
  42 .Ft int
  43 .Fn brk "const void *addr"
  44 .Ft void *
  45 .Fn sbrk "intptr_t incr"
  46 .Sh DESCRIPTION
  47 .Bf -symbolic
  48 The
  49 .Fn brk
  50 and
  51 .Fn sbrk
  52 functions are legacy interfaces from before the
  53 advent of modern virtual memory management.
  54 They are deprecated and not present on the arm64 or riscv architectures.
  55 The
  56 .Xr mmap 2
  57 interface should be used to allocate pages instead.
  58 .Ef
  59 .Pp
  60 The
  61 .Fn brk
  62 and
  63 .Fn sbrk
  64 functions are used to change the amount of memory allocated in a
  65 process's data segment.
  66 They do this by moving the location of the
  67 .Dq break .
  68 The break is the first address after the end of the process's
  69 uninitialized data segment (also known as the
  70 .Dq BSS ) .
  71 .Pp
  72 The
  73 .Fn brk
  74 function
  75 sets the break to
  76 .Fa addr .
  77 .Pp
  78 The
  79 .Fn sbrk
  80 function raises the break by
  81 .Fa incr
  82 bytes, thus allocating at least
  83 .Fa incr
  84 bytes of new memory in the data segment.
  85 If
  86 .Fa incr
  87 is negative,
  88 the break is lowered by
  89 .Fa incr
  90 bytes.
  91 .Sh NOTES
  92 While the actual process data segment size maintained by the kernel will only
  93 grow or shrink in page sizes, these functions allow setting the break
  94 to unaligned values (i.e., it may point to any address inside the last
  95 page of the data segment).
  96 .Pp
  97 The current value of the program break may be determined by calling
  98 .Fn sbrk 0 .
  99 See also
 100 .Xr end 3 .
 101 .Pp
 102 The
 103 .Xr getrlimit 2
 104 system call may be used to determine
 105 the maximum permissible size of the
 106 data segment.
 107 It will not be possible to set the break
 108 beyond
 109 .Dq Va etext No + Va rlim.rlim_max
 110 where the
 111 .Va rlim.rlim_max
 112 value is returned from a call to
 113 .Fn getrlimit RLIMIT_DATA &rlim .
 114 (See
 115 .Xr end 3
 116 for the definition of
 117 .Va etext ) .
 118 .Sh RETURN VALUES
 119 .Rv -std brk
 120 .Pp
 121 The
 122 .Fn sbrk
 123 function returns the prior break value if successful;
 124 otherwise the value
 125 .Po Vt "void *" Pc Ns \-1
 126 is returned and the global variable
 127 .Va errno
 128 is set to indicate the error.
 129 .Sh ERRORS
 130 The
 131 .Fn brk
 132 and
 133 .Fn sbrk
 134 functions
 135 will fail if:
 136 .Bl -tag -width Er
 137 .It Bq Er EINVAL
 138 The requested break value was beyond the beginning of the data segment.
 139 .It Bq Er ENOMEM
 140 The data segment size limit, as set by
 141 .Xr setrlimit 2 ,
 142 was exceeded.
 143 .It Bq Er ENOMEM
 144 Insufficient space existed in the swap area
 145 to support the expansion of the data segment.
 146 .El
 147 .Sh SEE ALSO
 148 .Xr execve 2 ,
 149 .Xr getrlimit 2 ,
 150 .Xr mmap 2 ,
 151 .Xr end 3 ,
 152 .Xr free 3 ,
 153 .Xr malloc 3
 154 .Sh HISTORY
 155 The
 156 .Fn brk
 157 function appeared in
 158 .At v7 .
 159 .Fx 11.0
 160 introduced the arm64 and riscv architectures which do not support
 161 .Fn brk
 162 or
 163 .Fn sbrk .
 164 .Sh BUGS
 165 Mixing
 166 .Fn brk
 167 or
 168 .Fn sbrk
 169 with
 170 .Xr malloc 3 ,
 171 .Xr free 3 ,
 172 or similar functions will result in non-portable program behavior.
 173 .Pp
 174 Setting the break may fail due to a temporary lack of
 175 swap space.
 176 It is not possible to distinguish this
 177 from a failure caused by exceeding the maximum size of
 178 the data segment without consulting
 179 .Xr getrlimit 2 .
 180 .Pp
 181 .Fn sbrk
 182 is sometimes used to monitor heap use by calling with an argument of 0.
 183 The result is unlikely to reflect actual utilization in combination with an
 184 .Xr mmap 2
 185 based malloc.