Index for Section 3

Alphabetical listing for A

Bottom of page

amalloc(3)
NAME
  acalloc, acreate, adelete, afree, amallinfo, amalloc, amallopt,
  amallocblksize, arealloc - arena memory allocator

LIBRARY
  Standard C Library (libc.so, libc.a)

SYNOPSIS
  #include <sys/types.h>
  #include <malloc.h>

  void *acreate (
	  void *addr, size_t len, int flags, void *ushdr,
	  void *(*grow_func)(size_t, void *));
  int adelete (void *ap);
  void *amalloc (
	  size_t size, void *ap);
  void afree (
	  void *ptr, void *ap);
  void *arealloc (
	  void *ptr, size_t size, void *ap);
  void *acalloc (
	  size_t nelem, size_t elsize, void *ap);
  size_t amallocblksize (
	  void *ptr, void *ap);

  The following function definitions are provided only for System V
  compatibility:

  int amallopt (
	  int cmd, int value, void *ap);
  struct mallinfo amallinfo (
	  void *ap);

DESCRIPTION
  The amalloc family of routines provides a main memory allocator based on
  the malloc(3) memory allocator. This allocator has been extended so that an
  arbitrary memory space ("arena") can be set up as an area from which to
  allocate memory.

  Calls to the amalloc family of routines differ from calls to the standard
  malloc(3) only in that an arena pointer must be supplied. This arena
  pointer is returned by a call to acreate.

  acreate
    Sets up an area defined as starting at virtual address addr and extending
    for len bytes. Arenas can be either growing or non-growing.

    An arena that is non-growing is constrained to use only up to len bytes
    of memory. The grow_func parameter should be NULL in this case.

    If the arena is "growable", len specifies the original size (minimum of
    1K bytes) and the grow_func parameter specifies a function that will be
    called when the allocator requires more memory.  Note that the original
    buffer addr will be used only for the arena header; the first time more
    memory is required, the "grow" function will be called.  This suggests
    that a minimal (1K) original buffer should be used when setting up a
    growable arena.

    The grow function will be called with two parameters: the number of bytes
    required and a pointer to the arena requiring the space. The number of
    bytes requested will always be a multiple of M_BLKSZ (see <malloc.h>
    header file). The function should return the address of a suitably large
    block of memory.  This block does not need to be contiguous with the
    original arena memory. This block could be obtained from a number of
    sources, such as by mapping in another file (by means of mmap(2)) or by
    calling malloc(3) to enlarge the program's data space.  If the grow
    function decides that it cannot provide any more space, it must return
    (void*)-1.

    The ushdr function is currently unused and must be NULL.

  adelete
    Causes any resources allocated for the arena (for example, mutexes) to be
    freed. Nothing is done with the arena memory itself.  No additional calls
    to any arena functions can be made after calling adelete.

  amalloc
    Returns a pointer to a block of at least size bytes suitably aligned for
    any use.

  afree
    Destroys the contents of a block previously allocated by amalloc,
    arealloc, or acalloc and makes this space available for future
    allocation.	 The argument to afree is a pointer to the block previously
    allocated by amalloc, arealloc, or acalloc.

    Undefined results will occur if the space assigned by any of the three
    arena allocator functions is overrun or if some random number is handed
    to afree. It is always permitted to pass NULL to afree.

  arealloc
    Changes the size of the block pointed to by ptr to size bytes and returns
    a pointer to the (possibly moved) block.  The contents will be unchanged,
    up to the lesser of the new and old sizes. In the special case of a null
    ptr, arealloc degenerates to amalloc.  A zero size causes the passed
    block to be freed.

  acalloc
    Allocates space for an array of nelem elements of size elsize.  The space
    is initialized to zeros.

  amallocblksize
    Returns the actual size of the block pointed to by ptr.  The returned
    size may be greater than the original requested size.

  amallopt
    Provides for control over the allocation algorithm. The available values
    for cmd are defined in the <malloc.h> header file.

    The amallopt function can be called repeatedly but, for most commands,
    not after the first small block is allocated.

  amallinfo
    Provides instrumentation describing space usage. It returns the mallinfo
    structure defined in the <malloc.h> header file.  The structure is zero
    until after the first space has been allocated from the arena.

  Each of the allocation routines returns a pointer to space suitably aligned
  for storage of any type of object.

RETURN VALUES
  The acreate function returns NULL and sets errno if either len is less than
  1K or the MEM_SHARED flag is passed.

  The amalloc, arealloc, and acalloc functions return a NULL pointer if there
  is not enough available memory.  When arealloc returns NULL, the block
  pointed to by ptr is left intact. If amallopt is called after any
  allocation (for most cmd arguments) or if cmd or value is invalid, non-zero
  is returned.	Otherwise, it returns zero.

RELATED INFORMATION
  Functions: malloc(3)

Index for Section 3

Alphabetical listing for A

Top of page