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