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

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