BRKCTL(S) XENIX System V BRKCTL(S)
Name
brkctl - Allocates data in a far segment.
Syntax
#include <sys/brk.h>
char far *brkctl(command, increment, ptr)
int command;
long increment;
char far *ptr;
Description
The brkctl system call allocates and deallocates memory in
additional data segments in small and middle model programs.
In order for the C compiler to make use of the return values
in small and middle model programs, brkctl must be declared
to return a far pointer. To enable the `far' keyword for
small model C programs, the -Me option to the compiler must
be used. Middle model C programs require the -Mme option.
command is either BR_ARGSEG, BR_NEWSEG, or BR_IMPSEG.
increment is a signed long increment. If positive, it must
be less than 64K; if negative, its absolute value must be
less than the sum of the total memory in all far segments
plus the amount allocated in the near segment after process
creation.
ptr is used only when command is BR_ARGSEG.
If increment is positive, brkctl returns a far pointer to
the base of at least increment number of bytes of memory
(see box on next page).
If the command is BR_IMPSEG, and a negative increment causes
one or more segments to be freed, the `segment in question'
(see the Return Values section) is the last remaining
segment that was not freed. BR_IMPSEG implies the use of the
last data segment. Unless the process is small or middle
model and currently has only one data segment, a positive
increment that would overflow the last data segment causes a
new segment to be allocated.
If the command is BR_ARGSEG, the increment may not be more
negative than the size of the segment. The third argument
(ptr), is assumed to be a far pointer in all models; the
offset portion is never used.
If the command is BR_NEWSEG, the increment may not be
negative at all. Any memory allocated is guaranteed to be
at the base of a new segment.
Page 1 (printed 8/7/87)
BRKCTL(S) XENIX System V BRKCTL(S)
Return Value
brkctl() almost always returns a far pointer to the base of
the affected region, (char far *)-1 on error.
When the increment is greater than 0, the return value is a
pointer to the base of the newly allocated memory.
When the increment is less than or equal to 0, the return
value is a pointer to the first illegal byte in the segment
in question (usually the base of the deallocated memory). If
that segment is full (exactly 64K bytes), the return value
will be a pointer to the base of the next segment (which may
or may not exist).
_________________________________________________________________
| Command Increment Ptr Action |
| ______________________________________________________________|__
| BR_ARGSEG 0 <valid far ptr> report on |
| segment |
| BR_ARGSEG other <valid far ptr> increment |
| specified |
| segment |
| |
| BR_NEWSEG 0 - allocate new |
| segment, size = |
| 0 |
| BR_NEWSEG other - allocate new |
| segment, size = |
| increment |
| |
| BR_IMPSEG 0 - report on last |
| segment; may |
| free up empty |
| segment(s). |
| BR_IMPSEG other - increment last |
| segment; on |
| large model (or |
| small and |
| middle model |
| with mutiple |
| data segments) |
| may allocate |
| new segment. |
|________________________________________________________________|
See Also
cc(CP), ld(CP), machine(M), malloc(S), sbrk(S)
Page 2 (printed 8/7/87)
BRKCTL(S) XENIX System V BRKCTL(S)
Notes
The brkctl system call should be used only for dynamically
allocating additional segments in small and middle model
programs. All other uses should be avoided in favor of
sbrk(S), malloc(S), and other standard UNIX system services.
The functionality of brkctl may change in future releases.
brkctl is currently available only on protected mode
In all models, the `near' data segment must be the first
data segment.
brkctl calls with BR_IMPSEG and a negative increment that
would affect a shared data segment are refused.
Page 3 (printed 8/7/87)