emulated/brk.2

   1 .\"     $NetBSD: brk.2,v 1.7 1995/02/27 12:31:57 cgd 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. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)brk.2       8.2 (Berkeley) 12/11/93
  35 .\"
  36 .Dd December 11, 1993
  37 .Dt BRK 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm brk ,
  41 .Nm sbrk
  42 .Nd change data segment size
  43 .Sh SYNOPSIS
  44 .Fd #include <unistd.h>
  45 .Ft void *
  46 .Fn brk "const void *addr"
  47 .Ft void *
  48 .Fn sbrk "int incr"
  49 .Sh DESCRIPTION
  50 .Bf -symbolic
  51 The brk and sbrk functions are historical curiosities
  52 left over from earlier days before the advent of virtual memory management.
  53 .Ef
  54 The
  55 .Fn brk
  56 function
  57 sets the break or lowest address
  58 of a process's data segment (uninitialized data) to
  59 .Fa addr
  60 (immediately above bss).
  61 Data addressing is restricted between
  62 .Fa addr
  63 and the lowest stack pointer to the stack segment.
  64 Memory is allocated by
  65 .Fa brk
  66 in page size pieces;
  67 if
  68 .Fa addr
  69 is not evenly divisible by the system page size, it is
  70 increased to the next page boundary.
  71 .Pp
  72 .\" The
  73 .\" .Nm sbrk
  74 .\" function
  75 .\" allocates chunks of
  76 .\" .Fa incr
  77 .\" bytes
  78 .\" to the process's data space
  79 .\" and returns an address pointer.
  80 .\" The
  81 .\" .Xr malloc 3
  82 .\" function utilizes
  83 .\" .Nm sbrk .
  84 .\" .Pp
  85 The current value of the program break is reliably returned by
  86 .Dq Li sbrk(0)
  87 (see also
  88 .Xr end 3 ) .
  89 The
  90 .Xr getrlimit 2
  91 system call may be used to determine
  92 the maximum permissible size of the
  93 .Em data
  94 segment;
  95 it will not be possible to set the break
  96 beyond the
  97 .Em rlim_max
  98 value returned from a call to
  99 .Xr getrlimit ,
 100 e.g.
 101 .Dq qetext + rlp\(->rlim_max.
 102 (see
 103 .Xr end 3
 104 for the definition of
 105 .Em etext ) .
 106 .Sh RETURN VALUES
 107 .Nm Brk
 108 returns a pointer to the new end of memory if successful;
 109 otherwise -1 with
 110 .Va errno
 111 set to indicate why the allocation failed.
 112 The
 113 .Nm sbrk
 114 function returns a pointer to the base of the new storage if successful;
 115 otherwise -1 with
 116 .Va errno
 117 set to indicate why the allocation failed.
 118 .Sh ERRORS
 119 .Xr Sbrk
 120 will fail and no additional memory will be allocated if
 121 one of the following are true:
 122 .Bl -tag -width Er
 123 .It Bq Er ENOMEM
 124 The limit, as set by
 125 .Xr setrlimit 2 ,
 126 was exceeded.
 127 .It Bq Er ENOMEM
 128 The maximum possible size of a data segment (compiled into the
 129 system) was exceeded.
 130 .It Bq Er ENOMEM
 131 Insufficient space existed in the swap area
 132 to support the expansion.
 133 .El
 134 .Sh SEE ALSO
 135 .Xr execve 2 ,
 136 .Xr getrlimit 2 ,
 137 .Xr malloc 3 ,
 138 .Xr mmap 2 ,
 139 .Xr end 3
 140 .Sh BUGS
 141 Setting the break may fail due to a temporary lack of
 142 swap space.  It is not possible to distinguish this
 143 from a failure caused by exceeding the maximum size of
 144 the data segment without consulting
 145 .Xr getrlimit .
 146 .Sh HISTORY
 147 A
 148 .Fn brk
 149 function call appeared in
 150 .At v7 .