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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)brk.2       8.4 (Berkeley) 5/1/95
  33 .\" $FreeBSD: src/lib/libc/sys/brk.2,v 1.13.2.10 2002/03/04 12:00:31 dwmalone Exp $
  34 .\" $DragonFly: src/lib/libc/sys/brk.2,v 1.3 2006/02/17 19:35:06 swildner Exp $
  35 .\"
  36 .Dd July 12, 1999
  37 .Dt BRK 2
  38 .Os
  39 .Sh NAME
  40 .Nm brk ,
  41 .Nm sbrk
  42 .Nd change data segment size
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In unistd.h
  48 .Ft int
  49 .Fn brk "const void *addr"
  50 .Ft void *
  51 .Fn sbrk "intptr_t incr"
  52 .Sh DESCRIPTION
  53 .Bf -symbolic
  54 The
  55 .Fn brk
  56 and
  57 .Fn sbrk
  58 functions are legacy interfaces from before the
  59 advent of modern virtual memory management.
  60 .Ef
  61 .Pp
  62 The
  63 .Fn brk
  64 and
  65 .Fn sbrk
  66 functions are used to change the amount of memory allocated in a
  67 process's data segment.
  68 They do this by moving the location of the
  69 .Dq break .
  70 The break is the first address after the end of the process's
  71 uninitialized data segment (also known as the
  72 .Dq BSS ) .
  73 .Pp
  74 The
  75 .Fn brk
  76 function
  77 sets the break to
  78 .Fa addr .
  79 .Pp
  80 The
  81 .Fn sbrk
  82 function raises the break by
  83 .Fa incr
  84 bytes, thus allocating at least
  85 .Fa incr
  86 bytes of new memory in the data segment.
  87 If
  88 .Fa incr
  89 is negative,
  90 the break is lowered by
  91 .Fa incr
  92 bytes.
  93 .Sh NOTES
  94 While the actual process data segment size maintained by the kernel will only
  95 grow or shrink in page sizes, these functions allow setting the break
  96 to unaligned values (i.e., it may point to any address inside the last
  97 page of the data segment).
  98 .Pp
  99 The current value of the program break may be determined by calling
 100 .Fn sbrk 0 .
 101 See also
 102 .Xr end 3 .
 103 .Pp
 104 The
 105 .Xr getrlimit 2
 106 system call may be used to determine
 107 the maximum permissible size of the
 108 data segment.
 109 It will not be possible to set the break
 110 beyond
 111 .Dq Va etext No + Va rlim.rlim_max
 112 where the
 113 .Va rlim.rlim_max
 114 value is returned from a call to
 115 .Fn getrlimit RLIMIT_DATA &rlim .
 116 (See
 117 .Xr end 3
 118 for the definition of
 119 .Va etext ) .
 120 .Sh RETURN VALUES
 121 .Rv -std brk
 122 .Pp
 123 The
 124 .Fn sbrk
 125 function returns the prior break value if successful;
 126 otherwise the value
 127 .Po Vt "void *" Pc Ns \-1
 128 is returned and the global variable
 129 .Va errno
 130 is set to indicate the error.
 131 .Sh ERRORS
 132 .Fn brk
 133 or
 134 .Fn sbrk
 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 A
 156 .Fn brk
 157 function call appeared in
 158 .At v7 .
 159 .Sh BUGS
 160 Mixing
 161 .Fn brk
 162 or
 163 .Fn sbrk
 164 with
 165 .Xr malloc 3 ,
 166 .Xr free 3 ,
 167 or similar functions will result in non-portable program behavior.
 168 .Pp
 169 Setting the break may fail due to a temporary lack of
 170 swap space.
 171 It is not possible to distinguish this
 172 from a failure caused by exceeding the maximum size of
 173 the data segment without consulting
 174 .Xr getrlimit 2 .