shmalloc(3C)

NAME
     shmalloc, shfree, shmemalign, shrealloc, shmalloc_check,
     shmalloc_stats - Symmetric heap memory management functions

SYNOPSIS
     #include <mpp/shmem.h>

     void *shmalloc(size_t size);

     void shfree(void *ptr);

     void *shrealloc(void *ptr, size_t size);

     void *shmemalign(size_t alignment, size_t size);

     int shmalloc_check(int level);

     void shmalloc_stats(int level);

     extern long malloc_error;

STANDARDS
     SGI extension

DESCRIPTION
     The shmalloc function returns a pointer to a block of at least size
     bytes suitably aligned for any use.  This space is allocated from the
     symmetric heap (in contrast to malloc(3C), which allocates from the
     private heap).

     The shmemalign function allocates a block in the symmetric heap that
     has a byte alignment specified by the alignment argument.

     The shfree function causes the block to which ptr points to be
     deallocated, that is, made available for further allocation.  If ptr
     is a null pointer, no action occurs; otherwise, if the argument does
     not match a pointer earlier returned by a symmetric heap function, or
     if the space has already been deallocated, malloc_error is set to
     indicate the error, and shfree returns.

     The shrealloc function changes the size of the block to which ptr
     points to the size (in bytes) specified by size.  The contents of the
     block are unchanged up to the lesser of the new and old sizes.  If the
     new size is larger, the value of the newly allocated portion of the
     block is indeterminate.  If ptr is a null pointer, the shrealloc
     function behaves like the shmalloc function for the specified size.
     If size is 0 and ptr is not a null pointer, the block to which it
     points is freed.  Otherwise, if ptr does not match a pointer earlier
     returned by a symmetric heap function, or if the space has already
     been deallocated, the malloc_error variable is set to indicate the
     error, and shrealloc returns a null pointer.  If the space cannot be
     allocated, the block to which ptr points is unchanged.

     The shmalloc, shfree, and shrealloc functions are provided so that
     multiple PEs in an application can allocate symmetric, remotely
     accessible memory blocks.  these memory blocks can then be used with
     the symmetric memory (shmem) library.  Each of these functions call
     the shmem_barrier_all(3) function before returning; this ensures that
     all PEs participate in the memory allocation, and that the memory on
     other PEs can be used as soon as the local PE returns.  The user is
     responsible for calling these functions with identical argument(s) on
     all PEs; if differing size arguments are used, subsequent calls may
     not return the same symmetric heap address on all PEs.

     The shmalloc_check function checks the consistency of shmalloc's
     memory structure.  If level is less than 0, shmalloc_check silently
     performs validation of the symmetric heap, and returns 0 if the heap
     is consistent, or nonzero if the heap has been corrupted.  If level
     equals 0, shmalloc_check prints a message to stderr that describes the
     first inconsistency found.  If level is greater than  0,
     shmalloc_check prints a line to stderr that describes each symmetric
     heap block in addition to checking the symmetric heap.

     The shmalloc_stats function prints out memory manager statistics and
     heap block information to stdout.  If level equals 0, shmalloc_stats
     reports the number of calls to each symmetric heap function, as well
     as summary statistics on the number and total size of the busy blocks,
     free blocks, and "spec" blocks (that is, blocks that are created by
     user calls to shsbreak) in the symmetric heap.  If level equals 1,
     shmalloc_stats prints a line with a * for each busy block, a . for
     each free block, and a @ for each "spec" block, in addition to the
     level 0 statistics.  If level equals 2, shmalloc_stats prints a line
     that describes each symmetric heap block, in addition to the level 0
     statistics.  The number of calls for each function are available only
     by linking with the libmalloc library; all of the other information is
     available in the default memory manager.

CAUTIONS
     The shmalloc, shfree, and shrealloc functions differ from the private
     heap allocation functions in that all PEs in an application must call
     them (a barrier is used to ensure this).  The shmalloc_check, and
     shmalloc_stats functions do not use a barrier, and can be used by a
     subset of all PEs.

RETURN VALUES
     The shmalloc function returns a pointer to the allocated space (which
     should be identical on all PEs); otherwise, it returns a null pointer
     (with malloc_error set).

     The shfree and shmalloc_stats functions return no value.

     The shrealloc function returns a pointer to the allocated space (which
     may have moved); otherwise, it returns a null pointer (with
     malloc_error set).

     If the symmetric heap has been corrupted, the shmalloc_check function
     returns nonzero; otherwise, it returns 0.

SEE ALSO
     intro_shmem(3), malloc(3C), malloc.h(3C)

     brk(2)