1.\" $OpenBSD: brk.2,v 1.24 2019/09/08 22:50:59 schwarze 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: September 8 2019 $ 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.In 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.Fa rlim_max 98value returned from a call to 99.Xr getrlimit 2 , 100e.g., 101.Ql etext + rlp->rlim_max 102(see 103.Xr end 3 104for the definition of 105.Em etext ) . 106.Sh RETURN VALUES 107.Rv -std brk 108.Pp 109The 110.Fn sbrk 111function returns a pointer to the base of the new storage if successful; 112otherwise \-1 with 113.Va errno 114set to indicate why the allocation failed. 115.Sh ERRORS 116.Fn sbrk 117will fail and no additional memory will be allocated if 118one of the following are true: 119.Bl -tag -width Er 120.It Bq Er ENOMEM 121The limit, as set by 122.Xr setrlimit 2 , 123was exceeded. 124.It Bq Er ENOMEM 125The maximum possible size of a data segment (compiled into the 126system) was exceeded. 127.It Bq Er ENOMEM 128Insufficient space existed in the swap area 129to support the expansion. 130.El 131.Sh SEE ALSO 132.Xr execve 2 , 133.Xr getrlimit 2 , 134.Xr mmap 2 , 135.Xr end 3 , 136.Xr malloc 3 137.Sh HISTORY 138A predecessor 139.Fn break 140appeared in 141.At v1 . 142The 143.Fn sbrk 144function call first appeared in 145.At v4 146and 147.Fn brk 148in 149.At v6 . 150.Sh BUGS 151Setting the break may fail due to a temporary lack of swap space. 152It is not possible to distinguish this from a failure caused by exceeding 153the maximum size of the data segment without consulting 154.Xr getrlimit 2 . 155