1.\" $NetBSD: brk.2,v 1.28 2002/10/01 18:10:43 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. 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.4 (Berkeley) 5/1/95 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.Fd #include \*[Lt]unistd.h\*[Gt] 47.Ft int 48.Fn brk "void *addr" 49.Ft void * 50.Fn sbrk "intptr_t incr" 51.Sh DESCRIPTION 52.Bf -symbolic 53The brk and sbrk functions are legacy interfaces from before the 54advent of modern virtual memory management. 55.Ef 56.Pp 57The 58.Fn brk 59and 60.Fn sbrk 61functions are used to change the amount of memory allocated in a 62process's data segment. 63They do this by moving the location of the 64.Dq break . 65The break is the first address after the end of the process's 66uninitialized data segment (also known as the 67.Dq BSS ) . 68.Pp 69While the actual process data segment size maintained by the kernel will only 70grow or shrink in page sizes, these functions allow setting the break 71to unaligned values (i.e. it may point to any address inside the last 72page of the data segment). 73.Pp 74The 75.Fn brk 76function sets the break to 77.Fa addr . 78.Pp 79The 80.Fn sbrk 81function raises the break by at least 82.Fa incr 83bytes, thus allocating at least 84.Fa incr 85bytes of new memory in the data segment. 86If 87.Fa incr 88is negative, 89the break is lowered by 90.Fa incr 91bytes. 92.Pp 93.Fn sbrk 94returns the prior address of the break. 95The current value of the program break may be determined by calling 96.Fn sbrk 0 . 97(See also 98.Xr end 3 ) . 99.Pp 100The 101.Xr getrlimit 2 102system call may be used to determine 103the maximum permissible size of the 104.Em data 105segment; 106it will not be possible to set the break 107beyond the 108.Dv RLIMIT_DATA 109.Em rlim_max 110value returned from a call to 111.Xr getrlimit 2 , 112e.g. 113.Dq etext + rlim.rlim_max . 114(see 115.Xr end 3 116for the definition of 117.Em etext ) . 118.Sh RETURN VALUES 119.Fn brk 120returns 0 if successful; 121otherwise -1 with 122.Va errno 123set to indicate why the allocation failed. 124.Pp 125The 126.Fn sbrk 127function returns the prior break value if successful; 128otherwise ((void *)-1) is returned and 129.Va errno 130is set to indicate why the allocation failed. 131.Sh ERRORS 132.Fn brk 133or 134.Fn sbrk 135will fail and no additional memory will be allocated if 136one of the following are true: 137.Bl -tag -width Er 138.It Bq Er ENOMEM 139The limit, as set by 140.Xr setrlimit 2 , 141was exceeded. 142.It Bq Er ENOMEM 143The maximum possible size of a data segment (compiled into the 144system) was exceeded. 145.It Bq Er ENOMEM 146Insufficient space existed in the swap area 147to support the expansion. 148.El 149.Sh SEE ALSO 150.Xr execve 2 , 151.Xr getrlimit 2 , 152.Xr mmap 2 , 153.Xr end 3 , 154.Xr free 3 , 155.Xr malloc 3 , 156.Xr sysconf 3 157.Sh HISTORY 158A 159.Fn brk 160function call appeared in 161.At v7 . 162.Sh BUGS 163Note that 164mixing 165.Fn brk 166and 167.Fn sbrk 168with 169.Xr malloc 3 , 170.Xr free 3 , 171and similar functions may result in non-portable program 172behavior. 173Caution is advised. 174.Pp 175Setting the break may fail due to a temporary lack of swap space. 176It is not possible to distinguish this from a failure caused by 177exceeding the maximum size of the data segment without consulting 178.Xr getrlimit 2 . 179