=head1	NAME

dkmem - Dynamic memory allocation

=head1	SYNOPSIS

  #include <dkmem.h>

  void *dkmem_alloc(size_t elsize, size_t nelem);
  void  dkmem_free(void *ptr);
  void  dkmem_res(void *ptr, size_t bytes);
  void  dkmem_cpy(void *d, void *s, size_t n);
  int   dkmem_cmp(void *s1, void *s2, size_t n);

  #define dk_new(type,nelem) (t *)dkmem_alloc(sizeof(type, (size_t)nelem)
  #define dk_delete(ptr) dkmem_free((void *)ptr)
  #define DK_MEMRES(ptr,sz) ...
  #define DK_MEMCPY(d,s,n)  ...
  #define DK_MEMCMP(a,b,n)  ...

=head1	DESCRIPTION

dkmem_alloc() tries to allocate memory. The I<elsize> argument specifies
the size of one element in bytes, I<nelem> is the number of elements.
On success a pointer to the memory is returned. If this memory is not longer
needed, it must be released using the dkmem_free() function.

dkmem_free() releases memory allocated by dkmem_alloc(). The I<ptr> argument
is the pointer returned by dkmem_alloc().

dkmem_res() resets memory by filling it with zero bytes. The I<ptr>
argument is the pointer to the start of the memory region,
I<bytes> is the number of zero bytes to write.

dkmem_cpy() copies a memory range from start address I<s> to destination
address I<d>. The I<n> parameter is the number of bytes.

dkmem_cmp() compares two memory regions specified by start adresses
I<s1> and I<s2>. The length of the regions is given by parameter I<n>.
If the first memory region is lexicographically "larger" than the second, the
function result is > 0. If I<s1> is "smaller" than I<s2> the result is < 0.
If both memory regions are equal the function result is 0.

The dk_new() and dk_delete() macros allow a more convenient use of the
functions.

The DK_MEM...() macros use native system functions
(bzero/memset, bcopy/memcpy, bcmp/memcmp) if available, otherwise the
fallback functions provided by the module itself.

It is recommended to use the macros instead of the functions.

=head1	RETURN VALUES

Functions returning pointers return a valid pointer on success, NULL
on errors.

The return value of dkmem_cmp() depends on which of the memory regions
is larger.

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2001-2008, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
