[unix-history] / usr / src / lib / libc / sys / brk.2

.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)brk.2	8.2 (Berkeley) %G%
.\"
.Dd 
.Dt BRK 2
.Os BSD 4
.Sh NAME
.Nm brk ,
.Nm sbrk
.Nd change data segment size
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Ft char
.Fn *brk "const char *addr"
.Ft char *
.Fn *sbrk "int incr"
.Sh DESCRIPTION
.Bf -symbolic
The brk and sbrk functions are historical curiosities
left over from earlier days before the advent of virtual memory management.
.Ef
The
.Fn brk
function
sets the break or lowest address
of a process's data segment (uninitialized data) to
.Fa addr
(immediately above bss).
Data addressing is restricted between
.Fa addr
and the lowest stack pointer to the stack segment.
Memory is allocated by
.Fa brk
in page size pieces;
if
.Fa addr
is not evenly divisible by the system page size, it is
increased to the next page boundary.
.Pp
.\" The
.\" .Nm sbrk
.\" function
.\" allocates chunks of
.\" .Fa incr
.\" bytes
.\" to the process's data space
.\" and returns an address pointer.
.\" The
.\" .Xr malloc 3
.\" function utilizes
.\" .Nm sbrk .
.\" .Pp
The current value of the program break is reliably returned by
.Dq Li sbrk(0)
(see also 
.Xr end 3 ) .
The
.Xr getrlimit 2
system call may be used to determine
the maximum permissible size of the
.Em data
segment;
it will not be possible to set the break
beyond the
.Em rlim_max
value returned from a call to
.Xr getrlimit ,
e.g.
.Dq qetext + rlp\(->rlim_max.
(see
.Xr end 3
for the definition of
.Em etext ) .
.Sh RETURN VALUES
.Nm Brk
returns a pointer to the new end of memory if successful;
otherwise -1 with
.Va errno
set to indicate why the allocation failed.
The
.Nm sbrk
returns a pointer to the base of the new storage if successful;
otherwise -1 with
.Va errno
set to indicate why the allocation failed.
.Sh ERRORS
.Xr Sbrk
will fail and no additional memory will be allocated if
one of the following are true:
.Bl -tag -width [ENOMEM]
.It Bq Er ENOMEM
The limit, as set by
.Xr setrlimit 2 ,
was exceeded.
.It Bq Er ENOMEM
The maximum possible size of a data segment (compiled into the
system) was exceeded.
.It Bq Er ENOMEM
Insufficient space existed in the swap area
to support the expansion.
.El
.Sh SEE ALSO
.Xr execve 2 ,
.Xr getrlimit 2 ,
.Xr malloc 3 ,
.Xr end 3
.Sh BUGS
Setting the break may fail due to a temporary lack of
swap space.  It is not possible to distinguish this
from a failure caused by exceeding the maximum size of
the data segment without consulting 
.Xr getrlimit .
.Sh HISTORY
A
.Nm
function call appeared in Version 7 AT&T UNIX.
Commit	Line	Data
aaea5b2e KB	1	.\" Copyright (c) 1980, 1991, 1993
aaea5b2e KB	2	.\" The Regents of the University of California. All rights reserved.
1423f0e0	3	.\"
931b8415	4	.\" %sccs.include.redist.man%
1423f0e0	5	.\"
653ba8b6	6	.\" @(#)brk.2 8.2 (Berkeley) %G%
931b8415 CL	7	.\"
	8	.Dd
	9	.Dt BRK 2
	10	.Os BSD 4
	11	.Sh NAME
	12	.Nm brk ,
	13	.Nm sbrk
	14	.Nd change data segment size
	15	.Sh SYNOPSIS
	16	.Fd #include <sys/types.h>
	17	.Ft char
	18	.Fn brk "const char addr"
	19	.Ft char *
	20	.Fn *sbrk "int incr"
	21	.Sh DESCRIPTION
	22	.Bf -symbolic
	23	The brk and sbrk functions are historical curiosities
	24	left over from earlier days before the advent of virtual memory management.
	25	.Ef
	26	The
	27	.Fn brk
	28	function
	29	sets the break or lowest address
653ba8b6	30	of a process's data segment (uninitialized data) to
931b8415 CL	31	.Fa addr
	32	(immediately above bss).
	33	Data addressing is restricted between
	34	.Fa addr
	35	and the lowest stack pointer to the stack segment.
	36	Memory is allocated by
	37	.Fa brk
	38	in page size pieces;
	39	if
	40	.Fa addr
	41	is not evenly divisible by the system page size, it is
	42	increased to the next page boundary.
	43	.Pp
	44	.\" The
	45	.\" .Nm sbrk
	46	.\" function
	47	.\" allocates chunks of
	48	.\" .Fa incr
	49	.\" bytes
	50	.\" to the process's data space
	51	.\" and returns an address pointer.
	52	.\" The
	53	.\" .Xr malloc 3
	54	.\" function utilizes
	55	.\" .Nm sbrk .
	56	.\" .Pp
53d740be	57	The current value of the program break is reliably returned by
931b8415 CL	58	.Dq Li sbrk(0)
	59	(see also
	60	.Xr end 3 ) .
1423f0e0	61	The
931b8415	62	.Xr getrlimit 2
1423f0e0 KM	63	system call may be used to determine
1423f0e0 KM	64	the maximum permissible size of the
931b8415	65	.Em data
1fa16506	66	segment;
1423f0e0	67	it will not be possible to set the break
1fa16506	68	beyond the
931b8415	69	.Em rlim_max
1fa16506	70	value returned from a call to
931b8415 CL	71	.Xr getrlimit ,
	72	e.g.
	73	.Dq qetext + rlp\(->rlim_max.
90f5cfd5	74	(see
931b8415	75	.Xr end 3
1423f0e0	76	for the definition of
931b8415 CL	77	.Em etext ) .
	78	.Sh RETURN VALUES
	79	.Nm Brk
869d4b7e KM	80	returns a pointer to the new end of memory if successful;
	81	otherwise -1 with
	82	.Va errno
	83	set to indicate why the allocation failed.
931b8415 CL	84	The
931b8415 CL	85	.Nm sbrk
869d4b7e KM	86	returns a pointer to the base of the new storage if successful;
	87	otherwise -1 with
	88	.Va errno
	89	set to indicate why the allocation failed.
	90	.Sh ERRORS
	91	.Xr Sbrk
	92	will fail and no additional memory will be allocated if
	93	one of the following are true:
	94	.Bl -tag -width [ENOMEM]
	95	.It Bq Er ENOMEM
	96	The limit, as set by
	97	.Xr setrlimit 2 ,
	98	was exceeded.
	99	.It Bq Er ENOMEM
	100	The maximum possible size of a data segment (compiled into the
	101	system) was exceeded.
	102	.It Bq Er ENOMEM
	103	Insufficient space existed in the swap area
	104	to support the expansion.
	105	.El
931b8415 CL	106	.Sh SEE ALSO
	107	.Xr execve 2 ,
	108	.Xr getrlimit 2 ,
	109	.Xr malloc 3 ,
	110	.Xr end 3
	111	.Sh BUGS
1fa16506 KM	112	Setting the break may fail due to a temporary lack of
	113	swap space. It is not possible to distinguish this
	114	from a failure caused by exceeding the maximum size of
	115	the data segment without consulting
931b8415 CL	116	.Xr getrlimit .
	117	.Sh HISTORY
	118	A
	119	.Nm
	120	function call appeared in Version 7 AT&T UNIX.