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