Commit | Line | Data |
---|---|---|
1423f0e0 KM |
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 | .\" | |
53d740be | 5 | .\" @(#)brk.2 6.4 (Berkeley) %G% |
1423f0e0 | 6 | .\" |
fbce8e35 | 7 | .TH BRK 2 "" |
1423f0e0 KM |
8 | .UC 4 |
9 | .SH NAME | |
1fa16506 | 10 | brk, sbrk \- change data segment size |
1423f0e0 | 11 | .SH SYNOPSIS |
1fa16506 | 12 | .nf |
fbce8e35 KM |
13 | #include <sys/types.h> |
14 | .PP | |
1fa16506 | 15 | .ft B |
96a9406d DS |
16 | char *brk(addr) |
17 | char *addr; | |
1423f0e0 | 18 | .PP |
1fa16506 | 19 | .ft B |
96a9406d | 20 | char *sbrk(incr) |
1fa16506 KM |
21 | int incr; |
22 | .fi | |
1423f0e0 KM |
23 | .SH DESCRIPTION |
24 | .I Brk | |
1fa16506 KM |
25 | sets the system's idea of the lowest data segment |
26 | location not used by the program (called the break) | |
1423f0e0 KM |
27 | to |
28 | .I addr | |
1fa16506 KM |
29 | (rounded up to the next multiple of the system's page size). |
30 | Locations greater than | |
1423f0e0 KM |
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 | |
1fa16506 | 37 | .IR sbrk , |
1423f0e0 KM |
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 | |
1fa16506 | 44 | .I execve |
1423f0e0 KM |
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 | |
1fa16506 | 50 | .IR sbrk . |
1423f0e0 | 51 | .PP |
53d740be KM |
52 | The current value of the program break is reliably returned by |
53 | ``sbrk(0)'' (see also | |
54 | .IR end (3)). | |
1423f0e0 | 55 | The |
1fa16506 | 56 | .IR getrlimit (2) |
1423f0e0 KM |
57 | system call may be used to determine |
58 | the maximum permissible size of the | |
59 | .I data | |
1fa16506 | 60 | segment; |
1423f0e0 | 61 | it will not be possible to set the break |
1fa16506 KM |
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 | |
90f5cfd5 | 67 | (see |
1423f0e0 KM |
68 | .IR end (3) |
69 | for the definition of | |
90f5cfd5 | 70 | .IR etext ). |
1fa16506 | 71 | .SH "RETURN VALUE |
1423f0e0 KM |
72 | Zero is returned if the |
73 | .I brk | |
74 | could be set; | |
75 | \-1 if the program requests more | |
1fa16506 | 76 | memory than the system limit. |
1423f0e0 KM |
77 | .I Sbrk |
78 | returns \-1 if the break could not be set. | |
1fa16506 KM |
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) | |
1423f0e0 | 98 | .SH BUGS |
1fa16506 KM |
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 . |