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