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 | .\" | |
96a9406d | 5 | .\" @(#)brk.2 6.2 (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 KM |
51 | .PP |
52 | The | |
1fa16506 | 53 | .IR getrlimit (2) |
1423f0e0 KM |
54 | system call may be used to determine |
55 | the maximum permissible size of the | |
56 | .I data | |
1fa16506 | 57 | segment; |
1423f0e0 | 58 | it will not be possible to set the break |
1fa16506 KM |
59 | beyond the |
60 | .I rlim_max | |
61 | value returned from a call to | |
62 | .IR getrlimit , | |
63 | e.g. \*(lqetext + rlp\(->rlim_max.\*(rq | |
1423f0e0 KM |
64 | (See |
65 | .IR end (3) | |
66 | for the definition of | |
67 | .IR etext .) | |
1fa16506 | 68 | .SH "RETURN VALUE |
1423f0e0 KM |
69 | Zero is returned if the |
70 | .I brk | |
71 | could be set; | |
72 | \-1 if the program requests more | |
1fa16506 | 73 | memory than the system limit. |
1423f0e0 KM |
74 | .I Sbrk |
75 | returns \-1 if the break could not be set. | |
1fa16506 KM |
76 | .SH ERRORS |
77 | .I Sbrk | |
78 | will fail and no additional memory will be allocated if | |
79 | one of the following are true: | |
80 | .TP 15 | |
81 | [ENOMEM] | |
82 | The limit, as set by | |
83 | .IR setrlimit (2), | |
84 | was exceeded. | |
85 | .TP 15 | |
86 | [ENOMEM] | |
87 | The maximum possible size of a data segment (compiled into the | |
88 | system) was exceeded. | |
89 | .TP 15 | |
90 | [ENOMEM] | |
91 | Insufficient space existed in the swap area | |
92 | to support the expansion. | |
93 | .SH "SEE ALSO" | |
94 | execve(2), getrlimit(2), malloc(3), end(3) | |
1423f0e0 | 95 | .SH BUGS |
1fa16506 KM |
96 | Setting the break may fail due to a temporary lack of |
97 | swap space. It is not possible to distinguish this | |
98 | from a failure caused by exceeding the maximum size of | |
99 | the data segment without consulting | |
100 | .IR getrlimit . |