manual page distributed with 4.2BSD

SCCS-vsn: lib/libc/sys/brk.2 5.1

diff --git a/usr/src/lib/libc/sys/brk.2 b/usr/src/lib/libc/sys/brk.2
index a1d40e4..e9438ab 100644 (file)
--- a/usr/src/lib/libc/sys/brk.2
+++ b/usr/src/lib/libc/sys/brk.2
@@ -2,85 +2,97 @@
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"

-.\"    @(#)brk.2       4.1 (Berkeley) %G%
+.\"    @(#)brk.2       5.1 (Berkeley) %G%

 .\"
 .\"

-.TH BRK 2 
+.TH BRK 2 "27 July 1983"

 .UC 4
 .SH NAME
 .UC 4
 .SH NAME

-brk, sbrk, break \- change core allocation
+brk, sbrk \- change data segment size

 .SH SYNOPSIS
 .SH SYNOPSIS

-.B char *brk(addr)
+.nf
+.ft B
+caddr_t brk(addr)
+caddr_t addr;

 .PP
 .PP

-.B char *sbrk(incr)
+.ft B
+caddr_t sbrk(incr)
+int incr;
+.fi

 .SH DESCRIPTION
 .I Brk
 .SH DESCRIPTION
 .I Brk

-sets the system's idea of the lowest location not used by the program
-(called the break)
+sets the system's idea of the lowest data segment 
+location not used by the program (called the break)

 to
 .I addr
 to
 .I addr

-(rounded up to the next multiple of 64 bytes
-on the PDP11, 256 bytes on the Interdata 8/32,
-and 1024 bytes on a VAX-11).
-Locations not less than
+(rounded up to the next multiple of the system's page size).
+Locations greater than

 .I addr
 and below the stack pointer
 are not in the address space and will thus
 cause a memory violation if accessed.
 .PP
 In the alternate function
 .I addr
 and below the stack pointer
 are not in the address space and will thus
 cause a memory violation if accessed.
 .PP
 In the alternate function

-.I sbrk,
+.IR sbrk ,

 .I incr
 more bytes are added to the
 program's data space and a pointer to the
 start of the new area is returned.
 .PP
 When a program begins execution via
 .I incr
 more bytes are added to the
 program's data space and a pointer to the
 start of the new area is returned.
 .PP
 When a program begins execution via

-.I exec
+.I execve

 the break is set at the
 highest location defined by the program
 and data storage areas.
 Ordinarily, therefore, only programs with growing
 data areas need to use
 the break is set at the
 highest location defined by the program
 and data storage areas.
 Ordinarily, therefore, only programs with growing
 data areas need to use

-.IR break .
+.IR sbrk .

 .PP
 The
 .PP
 The

-.IR vlimit (2)
+.IR getrlimit (2)

 system call may be used to determine
 the maximum permissible size of the
 .I data
 system call may be used to determine
 the maximum permissible size of the
 .I data

-region;
+segment;

 it will not be possible to set the break
 it will not be possible to set the break

-beyond
-\*(lqetext + vlimit(LIM_DATA, \-1).\*(rq
+beyond the
+.I rlim_max
+value returned from a call to
+.IR getrlimit ,
+e.g. \*(lqetext + rlp\(->rlim_max.\*(rq

 (See
 .IR end (3)
 for the definition of
 .IR etext .)
 (See
 .IR end (3)
 for the definition of
 .IR etext .)

-.SH "SEE ALSO"
-exec(2),
-vlimit(2),
-malloc(3),
-end(3)
-.SH DIAGNOSTICS
+.SH "RETURN VALUE

 Zero is returned if the 
 .I brk
 could be set;
 \-1 if the program requests more
 Zero is returned if the 
 .I brk
 could be set;
 \-1 if the program requests more

-memory than the system limit
-or if too many segmentation
-registers would be required to implement the break.
+memory than the system limit.

 .I Sbrk
 returns \-1 if the break could not be set.
 .I Sbrk
 returns \-1 if the break could not be set.

+.SH ERRORS
+.I Sbrk
+will fail and no additional memory will be allocated if
+one of the following are true:
+.TP 15
+[ENOMEM]
+The limit, as set by
+.IR setrlimit (2),
+was exceeded.
+.TP 15
+[ENOMEM]
+The maximum possible size of a data segment (compiled into the
+system) was exceeded.
+.TP 15
+[ENOMEM]
+Insufficient space existed in the swap area
+to support the expansion.
+.SH "SEE ALSO"
+execve(2), getrlimit(2), malloc(3), end(3)

 .SH BUGS
 .SH BUGS

-Setting the break in the range
-0177701 to 0177777 (on the PDP11) is the same as setting it to zero.
-.SH "ASSEMBLER (PDP-11)"
-(break = 17.)
-.br
-.B sys break; addr
-.PP
-.I Break
-performs the function of
-.IR brk .
-The name of the routine differs from that in C
-for historical reasons.
+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 
+.IR getrlimit .