lib/libc/sys/brk.2

   1 .\"     $NetBSD: brk.2,v 1.32 2004/05/13 10:20:57 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)brk.2       8.4 (Berkeley) 5/1/95
  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 unistd.h
  43 .Ft int
  44 .Fn brk "void *addr"
  45 .Ft void *
  46 .Fn sbrk "intptr_t incr"
  47 .Sh DESCRIPTION
  48 .Bf -symbolic
  49 The brk and sbrk functions are legacy interfaces from before the
  50 advent of modern virtual memory management.
  51 .Ef
  52 .Pp
  53 The
  54 .Fn brk
  55 and
  56 .Fn sbrk
  57 functions are used to change the amount of memory allocated in a
  58 process's data segment.
  59 They do this by moving the location of the
  60 .Dq break .
  61 The break is the first address after the end of the process's
  62 uninitialized data segment (also known as the
  63 .Dq BSS ) .
  64 .Pp
  65 While the actual process data segment size maintained by the kernel will only
  66 grow or shrink in page sizes, these functions allow setting the break
  67 to unaligned values (i.e. it may point to any address inside the last
  68 page of the data segment).
  69 .Pp
  70 The
  71 .Fn brk
  72 function sets the break to
  73 .Fa addr .
  74 .Pp
  75 The
  76 .Fn sbrk
  77 function raises the break by at least
  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 .Pp
  89 .Fn sbrk
  90 returns the prior address of the break.
  91 The current value of the program break may be determined by calling
  92 .Fn sbrk 0 .
  93 (See also
  94 .Xr end 3 ) .
  95 .Pp
  96 The
  97 .Xr getrlimit 2
  98 system call may be used to determine
  99 the maximum permissible size of the
 100 .Em data
 101 segment;
 102 it will not be possible to set the break
 103 beyond the
 104 .Dv RLIMIT_DATA
 105 .Em rlim_max
 106 value returned from a call to
 107 .Xr getrlimit 2 ,
 108 e.g.
 109 .Dq etext + rlim.rlim_max .
 110 (see
 111 .Xr end 3
 112 for the definition of
 113 .Em etext ) .
 114 .Sh RETURN VALUES
 115 .Fn brk
 116 returns 0 if successful;
 117 otherwise \-1 with
 118 .Va errno
 119 set to indicate why the allocation failed.
 120 .Pp
 121 The
 122 .Fn sbrk
 123 function returns the prior break value if successful;
 124 otherwise ((void *)\-1) is returned and
 125 .Va errno
 126 is set to indicate why the allocation failed.
 127 .Sh ERRORS
 128 .Fn brk
 129 or
 130 .Fn sbrk
 131 will fail and no additional memory will be allocated if
 132 one of the following are true:
 133 .Bl -tag -width Er
 134 .It Bq Er ENOMEM
 135 The limit, as set by
 136 .Xr setrlimit 2 ,
 137 was exceeded.
 138 .It Bq Er ENOMEM
 139 The maximum possible size of a data segment (compiled into the
 140 system) was exceeded.
 141 .It Bq Er ENOMEM
 142 Insufficient space existed in the swap area
 143 to support the expansion.
 144 .El
 145 .Sh SEE ALSO
 146 .Xr execve 2 ,
 147 .Xr getrlimit 2 ,
 148 .Xr mmap 2 ,
 149 .Xr end 3 ,
 150 .Xr free 3 ,
 151 .Xr malloc 3 ,
 152 .Xr sysconf 3
 153 .Sh HISTORY
 154 A
 155 .Fn brk
 156 function call appeared in
 157 .At v7 .
 158 .Sh BUGS
 159 Note that
 160 mixing
 161 .Fn brk
 162 and
 163 .Fn sbrk
 164 with
 165 .Xr malloc 3 ,
 166 .Xr free 3 ,
 167 and similar functions may result in non-portable program
 168 behavior.
 169 Caution is advised.
 170 .Pp
 171 Setting the break may fail due to a temporary lack of swap space.
 172 It is not possible to distinguish this from a failure caused by
 173 exceeding the maximum size of the data segment without consulting
 174 .Xr getrlimit 2 .