*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> acalloc (3)              



NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

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

       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 );

LIBRARY    [Toc]    [Back]

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

PARAMETERS    [Toc]    [Back]

       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    [Toc]    [Back]

       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 parameter
       is not allowed in nacreate().  MEM_NONCONCURRENT --  Turns
       off  all  attempts  to  use locking and atomic updates for
       this arena when allocating 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 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.

              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 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().   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    [Toc]    [Back]

       The  acreate()  function  returns  NULL  and sets errno if
       either len is less than  1K  or  the  MEM_SHARED  flag  is

       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, nonzero is returned. Otherwise, it returns  zero.

SEE ALSO    [Toc]    [Back]

       Functions:     malloc(3),     nmmap(2),     numa_intro(3),

[ Back ]
 Similar pages
Name OS Title
usmalloc IRIX shared arena memory allocator
amalloc IRIX arbitrary arena main memory allocator
alloca FreeBSD memory allocator
alloca Linux memory allocator
alloca OpenBSD memory allocator
alloca NetBSD memory allocator
FREE OpenBSD kernel memory allocator
free NetBSD kernel memory allocator
valloc Tru64 Provide a memory allocator
realloc Tru64 Provide a memory allocator
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service