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 July 12, 1999
  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 sys/types.h
  42 .In unistd.h
  43 .Ft int
  44 .Fn brk "const void *addr"
  45 .Ft void *
  46 .Fn sbrk "intptr_t incr"
  47 .Sh DESCRIPTION
  48 .Bf -symbolic
  49 The
  50 .Fn brk
  51 and
  52 .Fn sbrk
  53 functions are legacy interfaces from before the
  54 advent of modern virtual memory management.
  55 .Ef
  56 .Pp
  57 The
  58 .Fn brk
  59 and
  60 .Fn sbrk
  61 functions are used to change the amount of memory allocated in a
  62 process's data segment.
  63 They do this by moving the location of the
  64 .Dq break .
  65 The break is the first address after the end of the process's
  66 uninitialized data segment (also known as the
  67 .Dq BSS ) .
  68 .Pp
  69 The
  70 .Fn brk
  71 function
  72 sets the break to
  73 .Fa addr .
  74 .Pp
  75 The
  76 .Fn sbrk
  77 function raises the break by
  78 .Fa incr
  79 bytes, thus allocating at least
  80 .Fa incr
  81 bytes of new memory in the data segment.
  82 If
  83 .Fa incr
  84 is negative,
  85 the break is lowered by
  86 .Fa incr
  87 bytes.
  88 .Sh NOTES
  89 While the actual process data segment size maintained by the kernel will only
  90 grow or shrink in page sizes, these functions allow setting the break
  91 to unaligned values (i.e., it may point to any address inside the last
  92 page of the data segment).
  93 .Pp
  94 The current value of the program break may be determined by calling
  95 .Fn sbrk 0 .
  96 See also
  97 .Xr end 3 .
  98 .Pp
  99 The
 100 .Xr getrlimit 2
 101 system call may be used to determine
 102 the maximum permissible size of the
 103 data segment.
 104 It will not be possible to set the break
 105 beyond
 106 .Dq Va etext No + Va rlim.rlim_max
 107 where the
 108 .Va rlim.rlim_max
 109 value is returned from a call to
 110 .Fn getrlimit RLIMIT_DATA &rlim .
 111 (See
 112 .Xr end 3
 113 for the definition of
 114 .Va etext ) .
 115 .Sh RETURN VALUES
 116 .Rv -std brk
 117 .Pp
 118 The
 119 .Fn sbrk
 120 function returns the prior break value if successful;
 121 otherwise the value
 122 .Po Vt "void *" Pc Ns \-1
 123 is returned and the global variable
 124 .Va errno
 125 is set to indicate the error.
 126 .Sh ERRORS
 127 The
 128 .Fn brk
 129 and
 130 .Fn sbrk
 131 functions
 132 will fail if:
 133 .Bl -tag -width Er
 134 .It Bq Er EINVAL
 135 The requested break value was beyond the beginning of the data segment.
 136 .It Bq Er ENOMEM
 137 The data segment size limit, as set by
 138 .Xr setrlimit 2 ,
 139 was exceeded.
 140 .It Bq Er ENOMEM
 141 Insufficient space existed in the swap area
 142 to support the expansion of the data segment.
 143 .El
 144 .Sh SEE ALSO
 145 .Xr execve 2 ,
 146 .Xr getrlimit 2 ,
 147 .Xr mmap 2 ,
 148 .Xr end 3 ,
 149 .Xr free 3 ,
 150 .Xr malloc 3
 151 .Sh HISTORY
 152 The
 153 .Fn brk
 154 function appeared in
 155 .At v7 .
 156 .Sh BUGS
 157 Mixing
 158 .Fn brk
 159 or
 160 .Fn sbrk
 161 with
 162 .Xr malloc 3 ,
 163 .Xr free 3 ,
 164 or similar functions will result in non-portable program behavior.
 165 .Pp
 166 Setting the break may fail due to a temporary lack of
 167 swap space.
 168 It is not possible to distinguish this
 169 from a failure caused by exceeding the maximum size of
 170 the data segment without consulting
 171 .Xr getrlimit 2 .