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