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