lib/silcutil/silcmemory.h

   1 /*
   2
   3   silcmemory.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1999 - 2002 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SilcMemoryAPI
  21  *
  22  * DESCRIPTION
  23  *
  24  * Basic utility functions for allocating memory. All SILC routines, and
  25  * applications use these functions when they need to allocate, manipulate
  26  * and free memory.
  27  *
  28  * Currently all allocation routines assert() that the memory was allocated
  29  * successfully. Hence, if memory allocation fails it is fatal error.
  30  *
  31  ***/
  32
  33 #ifndef SILCMEMORY_H
  34 #define SILCMEMORY_H
  35
  36 /* Prototypes */
  37
  38 /****f* silcutil/SilcMemoryAPI/silc_malloc
  39  *
  40  * SYNOPSIS
  41  *
  42  *    void *silc_malloc(size_t size);
  43  *
  44  * DESCRIPTION
  45  *
  46  *    Allocates memory of `size' bytes and returns pointer to the allocated
  47  *    memory area.  Free the memory by calling silc_free.
  48  *
  49  ***/
  50 void *silc_malloc(size_t size);
  51
  52 /****f* silcutil/SilcMemoryAPI/silc_calloc
  53  *
  54  * SYNOPSIS
  55  *
  56  *    void *silc_calloc(size_t items, size_t size);
  57  *
  58  * DESCRIPTION
  59  *
  60  *    Allocates memory of for an array of `items' elements of `size' bytes
  61  *    and returns pointer to the allocated memory area.  The memory area is
  62  *    also zeroed.  Free the memory by calling silc_free.
  63  *
  64  ***/
  65 void *silc_calloc(size_t items, size_t size);
  66
  67 /****f* silcutil/SilcMemoryAPI/silc_realloc
  68  *
  69  * SYNOPSIS
  70  *
  71  *    void *silc_realloc(void *ptr, size_t size);
  72  *
  73  * DESCRIPTION
  74  *
  75  *    Change the size of the memory block indicated by `ptr' to the new
  76  *    size of `size' bytes.  The contents of `ptr' will not be changed.
  77  *    If `ptr' is NULL the call is equivalent to silc_malloc.  If the
  78  *    `size' is zero (0) the call is equivalent to silc_free.  Free the
  79  *    memory by calling silc_free.
  80  *
  81  * NOTES
  82  *
  83  *    The pointer returned to the reallocated memory area might not be
  84  *    same as `ptr'.
  85  *
  86  ***/
  87 void *silc_realloc(void *ptr, size_t size);
  88
  89 /****f* silcutil/SilcMemoryAPI/silc_free
  90  *
  91  * SYNOPSIS
  92  *
  93  *    void silc_free(void *ptr);
  94  *
  95  * DESCRIPTION
  96  *
  97  *    Frees the memory area indicated by the `ptr'. If `ptr' is NULL no
  98  *    operation is performed.
  99  *
 100  ***/
 101 void silc_free(void *ptr);
 102
 103 /****f* silcutil/SilcMemoryAPI/silc_memdup
 104  *
 105  * SYNOPSIS
 106  *
 107  *    void *silc_memdup(const void *ptr, size_t size);
 108  *
 109  * DESCRIPTION
 110  *
 111  *    Duplicates the memory area indicated by `ptr' which is of size
 112  *    of `size' bytes. Returns pointer to the duplicated memory area.
 113  *    This NULL terminates the dupped memory area by allocating `size' + 1
 114  *    bytes, so this function can be used to duplicate strings that does
 115  *    not have NULL termination.
 116  *
 117  ***/
 118 void *silc_memdup(const void *ptr, size_t size);
 119
 120 #endif /* SILCMEMORY_H */