valloc(3C)

NAME

     malloc, calloc, free, memalign, realloc,  valloc,  alloca  -
     memory allocator

SYNOPSIS

     #include <stdlib.h>

     void *malloc(size_t size);

     void *calloc(size_t nelem, size_t elsize);

     void free(void *ptr);

     void *memalign(size_t alignment, size_t size);

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

     void *valloc(size_t size);

     #include <alloca.h>

     void *alloca(size_t size);

DESCRIPTION

     The  malloc()  and  free()  functions  provide   a   simple,
     general-purpose  memory  allocation  package.  The  malloc()
     function returns a pointer to a block of at least size bytes
     suitably  aligned for any use. If the space assigned by mal-
     loc() is overrun, the results are undefined.

     The argument to free() is a pointer to  a  block  previously
     allocated  by malloc(), calloc(), or realloc(). After free()
     is executed, this space is made available for further  allo-
     cation  by  the application, though not returned to the sys-
     tem. Memory is returned to the system only upon  termination
     of  the  application.  If   ptr is a null pointer, no action
     occurs. If a random number is passed to free(), the  results
     are undefined.

     The calloc() function allocates space for an array of  nelem
     elements of size elsize. The space is initialized to zeros.

     The memalign() function allocates size bytes on a  specified
     alignment  boundary  and  returns a pointer to the allocated
     block. The value of the returned address is guaranteed to be
     an  even  multiple of alignment. The value of alignment must
     be a power of two and must be greater than or equal  to  the
     size of a word.

     The realloc() function changes the size of the block pointed
     to by ptr to size bytes and returns a pointer to the (possi-
     bly moved) block. The contents will be unchanged up  to  the
     lesser  of  the new and old sizes. If ptr is NULL, realloc()
     behaves like malloc() for the specified size. If size  is  0
     and  ptr is not a null pointer, the space pointed to is made
     available for further allocation by the application,  though
     not returned to the system. Memory is returned to the system
     only upon termination of the application.

     The valloc() function  has  the  same  effect  as  malloc(),
     except that the allocated memory will be aligned to a multi-
     ple of the value returned by sysconf(_SC_PAGESIZE).

     The alloca() function allocates size bytes of space  in  the
     stack  frame  of  the  caller,  and returns a pointer to the
     allocated block. This temporary space is automatically freed
     when  the  caller  returns. If the allocated block is beyond
     the current stack limit, the  resulting  behavior  is  unde-
     fined.

RETURN VALUES

     Upon successful completion, each of the allocation functions
     returns  a pointer to space suitably aligned (after possible
     pointer coercion) for storage of any type of object.

     If  there  is  no  available  memory,  malloc(),  realloc(),
     memalign(),  valloc(),  and  calloc() return a null pointer.
     When realloc() is called with size > 0 and returns NULL, the
     block  pointed  to by ptr is left intact. If size, nelem, or
     elsize is 0, either a null pointer or a unique pointer  that
     can be passed to free() is returned.

     If malloc(), calloc(), or realloc() returns  unsuccessfully,
     errno will be set to indicate the error. The free() function
     does not set errno.

ERRORS

     The malloc(), calloc(), and realloc()  functions  will  fail
     if:

     ENOMEM
           The physical limits of the system are exceeded by size
           bytes of memory which cannot be allocated.

     EAGAIN
           There is not enough memory available to allocate  size
           bytes  of  memory; but the application could try again
           later.

USAGE

     Portable applications should avoid using valloc() but should
     instead  use  malloc()  or  mmap(2). On systems with a large
     page size, the  number  of  successful  valloc()  operations
     might be 0.
     Comparative features of malloc(3C), bsdmalloc(3MALLOC),  and
     malloc(3MALLOC) are as follows:

        o  The bsdmalloc(3MALLOC) routines afford better  perfor-
           mance, but are space-inefficient.

        o  The malloc(3MALLOC) routines are space-efficient,  but
           have slower performance.

        o  The standard, fully SCD-compliant malloc routines  are
           a trade-off between performance and space-efficiency.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  Interface Stability        |  malloc(), calloc(), free(),|
   |                             |  realloc(),   valloc()   are|
   |                             |  Standard;  memalign()   and|
   |                             |  alloca() are Stable.       |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|

SEE ALSO

     brk(2), getrlimit(2),  bsdmalloc(3MALLOC),  malloc(3MALLOC),
     mapmalloc(3MALLOC), watchmalloc(3MALLOC), attributes(5)

WARNINGS

     Undefined results will occur if the  size  requested  for  a
     block  of  memory  exceeds  the  maximum size of a process's
     heap, which can be obtained with getrlimit(2)

     The alloca() function is machine-, compiler-,  and  most  of
     all, system-dependent. Its use is strongly discouraged.