amalloc(3)						     Library Functions Manual							amalloc(3)

NAME

       acalloc, acreate, adelete, afree, amallinfo, amalloc, amallopt, amallocblksize, arealloc, nacreate - arena memory allocator

LIBRARY

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

SYNOPSIS

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

       void *acreate (
	       void *addr, size_t len, int flags, void *ushdr,
	       void *(*grow_func)(size_t, void *)); void *nacreate (int flags, memalloc_attr_t *attr) 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 num_elts, size_t elt_size, 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);

PARAMETERS

       A pointer to a buffer used to hold the arena header information.  The size of the buffer in bytes (minimum 1K).	Attributes of the arena as
       the bitwise inclusive OR of any combination of MEM_NOAUTOGROW and MEM_NONCONCURRENT.  Currently unused and must be NULL.   For  non-growing
       arenas,	NULL; for growing arenas, a function to be called when the allocator requires more memory.  Points to the memory allocation policy
       and attributes to be used for allocations from the new arena.  A pointer to the arena.  A number of bytes of memory.  A pointer to a  block
       of memory.  The number of elements in an array.	The size of each element in an array.  A command for the amallopt() function.

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() or nacreate().

       For  the acreate() and nacreate() functions, the flags parameter specifies the attributes of a newly created arena: MEM_NOAUTOGROW - Causes
       the grow_func argument to be ignored and inhibits any attempt to expand the arena beyond the size len of the initial buffer.  This  parame-
       ter  is	not allowed in nacreate().  MEM_NONCONCURRENT - Turns off all attempts to use locking and atomic updates for this arena when allo-
       cating and freeing memory.  This has an affect only when the calling code is multithreaded. In this case, allocations and frees	using  the
       arena  may  happen faster, but the user must be extremely careful to guarantee that no two threads reference this arena at the same time in
       arena operations.

       Function descriptions: Sets up an area defined as starting at virtual address addr and extending for len bytes. Arenas can be either  grow-
       ing 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.

	      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.	Allocates an arena header and sets up a new growable arena.  The  location
	      for the arena is determined automatically. The arena will use nmmap() internally to obtain memory from the operating system, passing
	      in the saved attr parameter.

	      Note that use of the MEM_NOAUTOGROW flag is not allowed in calls to nacreate(). The returned arena may be used in  all  other  arena
	      malloc  functions;  however,  it is not specified whether memory freed by afree() from this arena is ever released for reuse outside
	      the arena.  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().  Returns a pointer to a block of at least
	      size bytes suitably aligned for any use.	Destroys the contents of a block previously allocated by amalloc(), arealloc(),  or  acal-
	      loc()  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().  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.  Allocates
	      space for an array of num_elts elements of size elt_size.  The space is initialized to zeros.  Returns the actual size of the  block
	      pointed  to  by  ptr.   The returned size may be greater than the original requested size.  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.   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), nmmap(2), numa_intro(3), numa_types(4) delim off

																	amalloc(3)