brkctl(S) 6 January 1993 brkctl(S) Name brkctl - allocates data in a 286 far segment Syntax cc . . . -lbrkctl #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 286 programs. 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 BRARGSEG, BRFREESEG, BRNEWSEG, or BRIMPSEG. 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 BRARGSEG. 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 BRIMPSEG, 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. BRIMPSEG 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 incre- ment that would overflow the last data segment causes a new segment to be allocated. If the command is BRARGSEG, 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 BRNEWSEG, the increment may not be negative at all. Any memory allocated is guaranteed to be at the base of a new segment. BRFREESEG frees memory allocated by a previous call to BRNEWSEG. A use of the command is: if ((fp=(long)brkctl(BR_FREESEG, (long)sizeof(int)*921,fp0)) == -1) { /* error */ } 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 is a pointer to the base of the next segment (which may or may not exist). _________________________________________________________________________ Command Increment Ptr Action _________________________________________________________________________ BRARGSEG 0 <valid far ptr> report on seg- ment BRARGSEG other <valid far ptr> increment specified seg- ment BRNEWSEG 0 - allocate new segment, size = 0 BRNEWSEG other - allocate new segment, size = increment BRIMPSEG 0 - report on last segment; may free up empty segment(s) BRIMPSEG other - increment last segment; on large model (or small and mid- dle model with multiple data segments) may allocate new segment Example The example of brkctl below uses the BRNEWSEG parameter to allocate space for 20,000 integers in a far data segment (on a 286 machine) and fills this memory with the integers from 1 to 20,000. Remember to com- pile this program with the cc -Me option. #include <sys/brk.h> #define FNULL (int far*)0 #ifdef M_I386 #define FAILURE (int *)-1 #else #define FAILURE (int far*)-1 #endif main() { int i,j; #ifdef M_I386 int *fp, *brkctl(); #else int far *fp, far *brkctl(); /* both fars are necessary */ #endif fp=brkctl(BR_NEWSEG,(long)sizeof(int)*20000,FNULL); if (fp==FAILURE){ perror("brkctl failed"); exit(1); } for (i=0;i<20000;++i) fp[i]=i+1; for (i=0;i<20000;++i) printf("%d\n",fp[i]); } Notes The brkctl system call should be used only for dynamically allocating additional segments in 80286 small and middle model programs. All other uses should be avoided in favor of sbrk(S), malloc(S), and other standard system services. The functionality of brkctl may change in future releases. brkctl is currently available only in protected mode. In all models, the ``near'' data segment must be the first data segment. brkctl calls with BRIMPSEG and a negative increment that would affect a shared data segment are refused. See also cc(CP), ld(CP), machine(M), malloc(S), sbrk(S) Standards conformance brkctl is an extension of AT&T System V provided by the Santa Cruz Opera- tion.