SHBRK(3P)

NAME
shbrk, shsbrk - change shared data segment size

SYNOPSIS
C syntax:

#include <parallel/parallel.h>
caddr_t shbrk(addr)
caddr_t addr;

caddr_t shsbrk(incr)
int incr;

Pascal syntax

none

FORTRAN syntax

none

DESCRIPTION
For a set of parallel processes executing a single application, shbrk sets the system's idea of the lowest shared data segment location not used by the program (called the “shared break”) to addr (rounded up to the next multiple of the system's page size). Locations greater than addr and below the stack pointer or another memory mapped region (see mmap(2)) are not in the address space and will thus cause a memory violation if accessed.

In the alternate function, shsbrk, incr more bytes are added to the program's shared data space and a pointer to the start of the new area is returned.

When a program begins execution via execve, the shared break is set at the highest location defined by the program. Ordinarily, therefore, only programs with growing shared data areas need to use shsbrk.

When shbrk and shsbrk increase a program's address space, they also attempt to increase its allowable resident set size (see vm_ctl(2)).

RETURN VALUE
Zero is returned if the shared break could be set; -1 if the program requests more memory than the system limit. shsbrk returns -1 if the break could not be set.

ERRORS
shbrk and shsbrk will fail and no additional memory will be allocated if any of the following error conditions occur:

[EINVAL]
    The shared break address would be lowered.

[ENOMEM]
    The routine cannot allocate file system space to expand the file which has been memory mapped to the shared data segment (see mmap(2)). The routine tries to allocate file system space from directories in the following order:

    1. the directory indicated by the $TMPPATH environmental variable
    2. the current directory
    3. the user's home directory
    4. the directory /usr/tmp
    5. the directory /tmp

[ENOMEM]
    The limit, as set by setrlimit, was exceeded.

[ENOMEM]
    The new shared data segment would overlap the stack segment.

SEE ALSO
execve(2), getrlimit(2), shmalloc(3), end(3), vm_ctl(2), mmap(2), Guide to Parallel Programming

BUGS
At this time, the size of the shared data segment can only be increased.

The shared break cannot be set above the stack segment limit for any of the processes in the program. (Remember that each process can have a different stack size.) If a process sets the shared break above the bottom of any process's stack, any reference to the overlapping area of that stack causes a core dump and aborts the program with a status of SIGSEGV.

shbrk and shsbrk use the SIGSEGV signal and signal handler for internal purposes. Users who declare their own SIGSEGV handler cannot expect reliable results from these routines.

If a shbrk or shsbrk call causes the shared data segment to overlap a memory mapped region, the shared data segment replaces the mapped region.