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
  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 .Ef
  57 .Pp
  58 The
  59 .Fn brk
  60 and
  61 .Fn sbrk
  62 functions are used to change the amount of memory allocated in a
  63 process's data segment.
  64 They do this by moving the location of the
  65 .Dq break .
  66 The break is the first address after the end of the process's
  67 uninitialized data segment (also known as the
  68 .Dq BSS ) .
  69 .Pp
  70 The
  71 .Fn brk
  72 function
  73 sets the break to
  74 .Fa addr .
  75 .Pp
  76 The
  77 .Fn sbrk
  78 function raises the break by
  79 .Fa incr
  80 bytes, thus allocating at least
  81 .Fa incr
  82 bytes of new memory in the data segment.
  83 If
  84 .Fa incr
  85 is negative,
  86 the break is lowered by
  87 .Fa incr
  88 bytes.
  89 .Sh NOTES
  90 While the actual process data segment size maintained by the kernel will only
  91 grow or shrink in page sizes, these functions allow setting the break
  92 to unaligned values (i.e., it may point to any address inside the last
  93 page of the data segment).
  94 .Pp
  95 The current value of the program break may be determined by calling
  96 .Fn sbrk 0 .
  97 See also
  98 .Xr end 3 .
  99 .Pp
 100 The
 101 .Xr getrlimit 2
 102 system call may be used to determine
 103 the maximum permissible size of the
 104 data segment.
 105 It will not be possible to set the break
 106 beyond
 107 .Dq Va etext No + Va rlim.rlim_max
 108 where the
 109 .Va rlim.rlim_max
 110 value is returned from a call to
 111 .Fn getrlimit RLIMIT_DATA &rlim .
 112 (See
 113 .Xr end 3
 114 for the definition of
 115 .Va etext ) .
 116 .Sh RETURN VALUES
 117 .Rv -std brk
 118 .Pp
 119 The
 120 .Fn sbrk
 121 function returns the prior break value if successful;
 122 otherwise the value
 123 .Po Vt "void *" Pc Ns \-1
 124 is returned and the global variable
 125 .Va errno
 126 is set to indicate the error.
 127 .Sh ERRORS
 128 .Fn brk
 129 or
 130 .Fn sbrk
 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 A
 152 .Fn brk
 153 function call 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 .