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 .\" 3. 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: src/lib/libc/sys/brk.2,v 1.13.2.10 2002/03/04 12:00:31 dwmalone Exp $
  30 .\" $DragonFly: src/lib/libc/sys/brk.2,v 1.3 2006/02/17 19:35:06 swildner Exp $
  31 .\"
  32 .Dd July 12, 1999
  33 .Dt BRK 2
  34 .Os
  35 .Sh NAME
  36 .Nm brk ,
  37 .Nm sbrk
  38 .Nd change data segment size (obsolete)
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/types.h
  43 .In unistd.h
  44 .Ft int
  45 .Fn brk "const void *addr"
  46 .Ft void *
  47 .Fn sbrk "intptr_t incr"
  48 .Sh DESCRIPTION
  49 .Bf -symbolic
  50 The
  51 .Fn brk
  52 and
  53 .Fn sbrk
  54 functions are legacy interfaces from before the
  55 advent of modern virtual memory management.
  56 .Fn brk
  57 is no longer implemented by
  58 .Dx
  59 and
  60 .Fn sbrk
  61 has only limited functionality due to having to play nice with
  62 modern system calls such as
  63 .Xr mmap 2 .
  64 .Ef
  65 .Pp
  66 The
  67 .Fn brk
  68 and
  69 .Fn sbrk
  70 functions are used to change the amount of memory allocated in a
  71 process's data segment.
  72 They do this by moving the location of the
  73 .Dq break .
  74 The break is the first address after the end of the process's
  75 uninitialized data segment (also known as the
  76 .Dq BSS ) .
  77 .Pp
  78 The break range is limited by the
  79 .Dv RLIMIT_DATA
  80 resource limit applied to the process.
  81 .Pp
  82 The
  83 .Fn brk
  84 function
  85 sets the break to
  86 .Fa addr .
  87 .Dx
  88 no longer implements this function.
  89 .Pp
  90 The
  91 .Fn sbrk
  92 function raises the break by
  93 .Fa incr
  94 bytes, returning a pointer to the base of the new memory.
  95 .Pp
  96 In the traditional call, a negative
  97 .Fa incr
  98 lowers the break address by the specified number of bytes.
  99 However,
 100 .Dx
 101 no longer supports using this legacy function to lower the break
 102 address.  The reason is because the resource limit can be adjusted
 103 upward and downward at run-time and indirectly allow normal memory-mappings
 104 via
 105 .Fn mmap
 106 to infiltrate the traditional data area.  In addition, lowering the break
 107 address in this manner is not thread safe.
 108 Any attempt to lower the break point will return
 109 .Po Vt "void *" Pc Ns \-1
 110 and set errno to
 111 .Er EOPNOTSUPP .
 112 .Sh NOTES
 113 While the actual process data segment size maintained by the kernel will only
 114 grow or shrink in page sizes, these functions allow setting the break
 115 to unaligned values (i.e., it may point to any address inside the last
 116 page of the data segment).
 117 .Pp
 118 The current value of the program break may be determined by calling
 119 .Fn sbrk 0 .
 120 .Pp
 121 The
 122 .Fn sbrk
 123 function is thread-safe.
 124 See also
 125 .Xr end 3 .
 126 .Pp
 127 The
 128 .Xr getrlimit 2
 129 system call may be used to determine
 130 the maximum permissible size of the
 131 data segment.
 132 It will not be possible to set the break
 133 beyond
 134 .Dq Va etext No + Va rlim.rlim_max
 135 where the
 136 .Va rlim.rlim_max
 137 value is returned from a call to
 138 .Fn getrlimit RLIMIT_DATA &rlim .
 139 (See
 140 .Xr end 3
 141 for the definition of
 142 .Va etext ) .
 143 .Sh RETURN VALUES
 144 .Rv -std brk
 145 .Pp
 146 The
 147 .Fn sbrk
 148 function returns the prior break pointer if successful;
 149 otherwise the value
 150 .Po Vt "void *" Pc Ns \-1
 151 is returned and the global variable
 152 .Va errno
 153 is set to indicate the error.
 154 .Sh ERRORS
 155 .Fn brk
 156 or
 157 .Fn sbrk
 158 will fail if:
 159 .Bl -tag -width Er
 160 .It Bq Er EINVAL
 161 The requested break value was beyond the beginning of the data segment.
 162 .It Bq Er ENOMEM
 163 The data segment size limit, as set by
 164 .Xr setrlimit 2 ,
 165 was exceeded.
 166 .It Bq Er ENOMEM
 167 Insufficient space existed in the swap area
 168 to support the expansion of the data segment.
 169 .It Bq Er EOPNOTSUPP
 170 An attempt has been made to perform an action that is no longer supported
 171 by this function.
 172 .El
 173 .Sh SEE ALSO
 174 .Xr execve 2 ,
 175 .Xr getrlimit 2 ,
 176 .Xr mmap 2 ,
 177 .Xr end 3 ,
 178 .Xr free 3 ,
 179 .Xr malloc 3
 180 .Sh HISTORY
 181 A
 182 .Fn brk
 183 function call appeared in
 184 .At v7 .
 185 .Sh BUGS
 186 Mixing
 187 .Fn brk
 188 or
 189 .Fn sbrk
 190 with
 191 .Xr malloc 3 ,
 192 .Xr free 3 ,
 193 or similar functions will result in non-portable program behavior.
 194 .Pp
 195 Setting the break may fail due to a temporary lack of
 196 swap space.
 197 It is not possible to distinguish this
 198 from a failure caused by exceeding the maximum size of
 199 the data segment without consulting
 200 .Xr getrlimit 2 .