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