chiark - git - mdw - catacomb/blob - base/lmem.h

   1 /* -*-c-*-
   2  *
   3  * Locked memory allocation
   4  *
   5  * (c) 1999 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of Catacomb.
  11  *
  12  * Catacomb is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * Catacomb is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with Catacomb; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef CATACOMB_LMEM_H
  29 #define CATACOMB_LMEM_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Header files ------------------------------------------------------*/
  36
  37 #include <stddef.h>
  38
  39 #include <mLib/arena.h>
  40 #include <mLib/dstr.h>
  41
  42 /*----- Data structures ---------------------------------------------------*/
  43
  44 /* --- Block list --- *
  45  *
  46  * The block list is kept in normal memory, to avoid wasting precious locked
  47  * memory.  Entries are sorted into ascending address order to make
  48  * coalescing free blocks easier.  All blocks, free or not, are included in
  49  * the list.
  50  */
  51
  52 typedef struct l_node {
  53   struct l_node *next;                  /* Next free block in chain */
  54   char *p;                              /* Pointer to the block */
  55   size_t sz;                            /* Size of the block */
  56   unsigned f;                           /* Various flags */
  57 } l_node;
  58
  59 #define LF_ALLOC 1u
  60
  61 /* --- Locked memory buffer state --- */
  62
  63 typedef struct lmem {
  64   arena a;                              /* Arena header block */
  65   unsigned f;                           /* Various flags */
  66   char *p;                              /* Pointer to locked buffer */
  67   l_node *l;                            /* Pointer to block list */
  68   size_t sz;                            /* Size of locked buffer */
  69   size_t free;                          /* Size of free area */
  70   int err; char *emsg;                  /* Error indicators */
  71 } lmem;
  72
  73 #define LF_LOCKED 1u
  74
  75 /*----- Functions provided ------------------------------------------------*/
  76
  77 /* --- @l_init@ --- *
  78  *
  79  * Arguments:   @lmem *lm@ = pointer to locked memory descriptor
  80  *              @size_t sz@ = size of locked memory area requested
  81  *
  82  * Returns:     Zero if everything is fine, @+1@ if some insecure memory was
  83  *              allocated, and @-1@ if everything went horribly wrong.
  84  *
  85  * Use:         Initializes the locked memory manager.  This function is safe
  86  *              to call in a privileged program; privileges should usually be
  87  *              dropped after allocating the locked memory block.
  88  *
  89  *              You must call @sub_init@ before allocating locked memory
  90  *              buffers.
  91  */
  92
  93 extern int l_init(lmem */*lm*/, size_t /*sz*/);
  94
  95 /* --- @l_alloc@ --- *
  96  *
  97  * Arguments:   @lmem *lm@ = pointer to locked memory descriptor
  98  *              @size_t sz@ = size requested
  99  *
 100  * Returns:     Pointer to allocated memory.
 101  *
 102  * Use:         Allocates @sz@ bytes of locked memory.
 103  */
 104
 105 extern void *l_alloc(lmem */*lm*/, size_t /*sz*/);
 106
 107 /* --- @l_free@ --- *
 108  *
 109  * Arguments:   @lmem *lm@ = pointer to locked memory descriptor
 110  *              @void *p@ = pointer to block
 111  *
 112  * Returns:     ---
 113  *
 114  * Use:         Releases a block of locked memory.
 115  */
 116
 117 extern void l_free(lmem */*lm*/, void */*p*/);
 118
 119 /* --- @l_purge@ --- *
 120  *
 121  * Arguments:   @lmem *lm@ = pointer to locked memory descriptor
 122  *
 123  * Returns:     ---
 124  *
 125  * Use:         Purges all the free blocks in the buffer, and clears all of
 126  *              the locked memory.  Memory is not freed back to the system.
 127  */
 128
 129 extern void l_purge(lmem */*lm*/);
 130
 131 /* --- @l_destroy@ --- *
 132  *
 133  * Arguments:   @lmem *lm@ = pointer to locked memory descriptor
 134  *
 135  * Returns:     ---
 136  *
 137  * Use:         Disposes of a locked memory arena permanently.
 138  */
 139
 140 extern void l_destroy(lmem */*lm*/);
 141
 142 /* --- @l_report@ --- *
 143  *
 144  * Arguments:   @lmem *lm@ = pointer to locked memory descriptor
 145  *              @dstr *d@ = string to write the error message on
 146  *
 147  * Returns:     Zero if the buffer is fine, @+1@ if there was a problem
 148  *              getting locked memory but insecure stuff could be allocated,
 149  *              and @-1@ if not even insecure memory could be found.
 150  *
 151  * Use:         Returns a user-digestable explanation for the state of a
 152  *              locked memory buffer.  If the return code is zero, no message
 153  *              is emitted to the string @d@.
 154  */
 155
 156 extern int l_report(lmem */*lm*/, dstr */*d*/);
 157
 158 /*----- That's all, folks -------------------------------------------------*/
 159
 160 #ifdef __cplusplus
 161   }
 162 #endif
 163
 164 #endif