Return to brk.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

Annotation of 43BSDReno/lib/libc/sys/brk.2, revision 1.1.1.1

1.1       root        1: .\" Copyright (c) 1980 Regents of the University of California.
                      2: .\" All rights reserved.  The Berkeley software License Agreement
                      3: .\" specifies the terms and conditions for redistribution.
                      4: .\"
                      5: .\"    @(#)brk.2       6.4 (Berkeley) 6/17/86
                      6: .\"
                      7: .TH BRK 2 "June 17, 1986"
                      8: .UC 4
                      9: .SH NAME
                     10: brk, sbrk \- change data segment size
                     11: .SH SYNOPSIS
                     12: .nf
                     13: #include <sys/types.h>
                     14: .PP
                     15: .ft B
                     16: char *brk(addr)
                     17: char *addr;
                     18: .PP
                     19: .ft B
                     20: char *sbrk(incr)
                     21: int incr;
                     22: .fi
                     23: .SH DESCRIPTION
                     24: .I Brk
                     25: sets the system's idea of the lowest data segment 
                     26: location not used by the program (called the break)
                     27: to
                     28: .I addr
                     29: (rounded up to the next multiple of the system's page size).
                     30: Locations greater than
                     31: .I addr
                     32: and below the stack pointer
                     33: are not in the address space and will thus
                     34: cause a memory violation if accessed.
                     35: .PP
                     36: In the alternate function
                     37: .IR sbrk ,
                     38: .I incr
                     39: more bytes are added to the
                     40: program's data space and a pointer to the
                     41: start of the new area is returned.
                     42: .PP
                     43: When a program begins execution via
                     44: .I execve
                     45: the break is set at the
                     46: highest location defined by the program
                     47: and data storage areas.
                     48: Ordinarily, therefore, only programs with growing
                     49: data areas need to use
                     50: .IR sbrk .
                     51: .PP
                     52: The current value of the program break is reliably returned by
                     53: ``sbrk(0)'' (see also 
                     54: .IR end (3)).
                     55: The
                     56: .IR getrlimit (2)
                     57: system call may be used to determine
                     58: the maximum permissible size of the
                     59: .I data
                     60: segment;
                     61: it will not be possible to set the break
                     62: beyond the
                     63: .I rlim_max
                     64: value returned from a call to
                     65: .IR getrlimit ,
                     66: e.g. \*(lqetext + rlp\(->rlim_max.\*(rq
                     67: (see
                     68: .IR end (3)
                     69: for the definition of
                     70: .IR etext ).
                     71: .SH "RETURN VALUE
                     72: Zero is returned if the 
                     73: .I brk
                     74: could be set;
                     75: \-1 if the program requests more
                     76: memory than the system limit.
                     77: .I Sbrk
                     78: returns \-1 if the break could not be set.
                     79: .SH ERRORS
                     80: .I Sbrk
                     81: will fail and no additional memory will be allocated if
                     82: one of the following are true:
                     83: .TP 15
                     84: [ENOMEM]
                     85: The limit, as set by
                     86: .IR setrlimit (2),
                     87: was exceeded.
                     88: .TP 15
                     89: [ENOMEM]
                     90: The maximum possible size of a data segment (compiled into the
                     91: system) was exceeded.
                     92: .TP 15
                     93: [ENOMEM]
                     94: Insufficient space existed in the swap area
                     95: to support the expansion.
                     96: .SH "SEE ALSO"
                     97: execve(2), getrlimit(2), malloc(3), end(3)
                     98: .SH BUGS
                     99: Setting the break may fail due to a temporary lack of
                    100: swap space.  It is not possible to distinguish this
                    101: from a failure caused by exceeding the maximum size of
                    102: the data segment without consulting 
                    103: .IR getrlimit .

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.