chiark - git - mdw - become/blob - src/class.h

   1 /* -*-c-*-
   2  *
   3  * $Id: class.h,v 1.6 2003/10/12 00:14:55 mdw Exp $
   4  *
   5  * Handling classes of things nicely
   6  *
   7  * (c) 1998 EBI
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of `become'
  13  *
  14  * `Become' is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * `Become' 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 General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with `become'; if not, write to the Free Software Foundation,
  26  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 /*----- Revision history --------------------------------------------------*
  30  *
  31  * $Log: class.h,v $
  32  * Revision 1.6  2003/10/12 00:14:55  mdw
  33  * Major overhaul.  Now uses DSA signatures rather than the bogus symmetric
  34  * encrypt-and-hope thing.  Integrated with mLib and Catacomb.
  35  *
  36  * Revision 1.5  1998/04/23 13:22:44  mdw
  37  * Fix value of clNode_binop, required for bcquery.
  38  *
  39  * Revision 1.4  1998/01/12 16:45:53  mdw
  40  * Fix copyright date.
  41  *
  42  * Revision 1.3  1997/09/17  10:14:56  mdw
  43  * Complete rewrite to support class trees.  Makes the behaviour of the set
  44  * operators much more logical.
  45  *
  46  * Revision 1.2  1997/08/04 10:24:21  mdw
  47  * Sources placed under CVS control.
  48  *
  49  * Revision 1.1  1997/07/21  13:47:52  mdw
  50  * Initial revision
  51  *
  52  */
  53
  54 #ifndef CLASS_H
  55 #define CLASS_H
  56
  57 #ifdef __cplusplus
  58   extern "C" {
  59 #endif
  60
  61 /*----- Required headers --------------------------------------------------*/
  62
  63 #include <sys/types.h>
  64 #include <sys/socket.h>
  65 #include <netinet/in.h>
  66 #include <arpa/inet.h>
  67
  68 #include <mLib/sym.h>
  69
  70 /*----- Data structures ---------------------------------------------------*/
  71
  72 /* --- Class types --- */
  73
  74 enum {
  75
  76   /* --- Data types (user visible) --- *
  77    *
  78    * These bits encode what the user can think of as `types'.  They get used
  79    * for typechecking and things.
  80    */
  81
  82   clType_user = 0x01,                   /* Class of users */
  83   clType_command = 0x02,                /* Class of command strings */
  84   clType_host = 0x04,                   /* Class of host names */
  85   clType_all = 0x0F,                    /* All of the above (maintain me) */
  86   clType_mask = 0x0F,                   /* Mask for type flags */
  87
  88   /* --- Node types --- *
  89    *
  90    * A class actually looks suspiciously like a tree once things start
  91    * getting complicated.  These bits encode the type of node we've got here.
  92    */
  93
  94   clNode_any = 0x10,                    /* Magic type for the `all' class */
  95   clNode_immed = 0x20,                  /* Immediate data item */
  96   clNode_hash = 0x30,                   /* Hashtable of values */
  97   clNode_binop = 0x40,                  /* Binary operations start here */
  98   clNode_union = 0x40,                  /* Union of two classes */
  99   clNode_diff = 0x50,                   /* Difference of two classes */
 100   clNode_isect = 0x60,                  /* Intersection of two classes */
 101   clNode_mask = 0xF0,                   /* Mask for picking these out */
 102
 103   /* --- Other useful flags --- */
 104
 105   clFlag_friendly = 0x100               /* Item can be hashed with others */
 106 };
 107
 108 /* --- Class block --- */
 109
 110 typedef struct class_node {
 111   unsigned type;                        /* Class and node type, and flags */
 112   unsigned ref;                         /* Reference count */
 113   union {
 114     uid_t u;                            /* Immediate user id number */
 115     char *s;                            /* Immediate string value */
 116     sym_table t;                        /* Hash table for this class */
 117     struct {
 118       struct class_node *l, *r;         /* Left and right operands */
 119     } c;                                /* Class operands for binops */
 120   } v;                                  /* Value of this class node */
 121 } class_node;
 122
 123 /*----- Global variables --------------------------------------------------*/
 124
 125 extern class_node *class_all;           /* The match-everything class */
 126 extern class_node *class_none;          /* The match-nothing class */
 127
 128 /*----- Functions provided ------------------------------------------------*/
 129
 130 /* --- @class_fromString@ --- *
 131  *
 132  * Arguments:   @unsigned type@ = a type field
 133  *              @const char *s@ = pointer to string to copy
 134  *
 135  * Returns:     A pointer to a class node containing that string, typed to
 136  *              be the right thing.
 137  *
 138  * Use:         Given a string, wrap a class node around it.  The node has
 139  *              one reference (the one you get returned).  The string is
 140  *              copied, so you can get rid of your original one if you like.
 141  */
 142
 143 extern class_node *class_fromString(unsigned /*type*/, const char */*s*/);
 144
 145 /* --- @class_fromUser@ --- *
 146  *
 147  * Arguments:   @unsigned type@ = a type field
 148  *              @uid_t u@ = a user-id number
 149  *
 150  * Returns:     A pointer to a class node containing the uid, typed to be
 151  *              the thing you asked for.  Hopefully this will be
 152  *              @clType_user@.
 153  *
 154  * Use:         Given a uid, wrap a class node around it.
 155  */
 156
 157 extern class_node *class_fromUser(unsigned /*type*/, uid_t /*u*/);
 158
 159 /* --- @class_inc@ --- *
 160  *
 161  * Arguments:   @class_node *c@ = pointer to a class block
 162  *
 163  * Returns:     ---
 164  *
 165  * Use:         Adds a reference to the class definition.
 166  */
 167
 168 extern void class_inc(class_node */*c*/);
 169
 170 /* --- @class_dec@ --- *
 171  *
 172  * Arguments:   @class_node *c@ = pointer to a class block
 173  *
 174  * Returns:     ---
 175  *
 176  * Use:         Removes a reference to a class block.
 177  */
 178
 179 extern void class_dec(class_node */*c*/);
 180
 181 /* --- @class_mod@ --- *
 182  *
 183  * Arguments:   @class_node *c@ = pointer to a class node
 184  *
 185  * Returns:     A pointer to a class node, maybe the same one, maybe not,
 186  *              with a reference count of 1, containing the same data.
 187  *
 188  * Use:         Gives you a node which you can modify.  Don't call this
 189  *              for @class_all@ or @class_none@.
 190  */
 191
 192 extern class_node *class_mod(class_node */*c*/);
 193
 194 /* --- @class_union@ --- *
 195  *
 196  * Arguments:   @class_node *l@ = left argument
 197  *              @class_node *r@ = right argument
 198  *
 199  * Returns:     A class node representing the union of the two classes.
 200  *
 201  * Use:         Performs the union operation on classes.  If the types don't
 202  *              match, then a null pointer is returned.  Both @l@ and @r@
 203  *              may be modified, and will be decremented before they get
 204  *              returned to you.  If you don't want that to happen, ensure
 205  *              that you've claimed a reference to the original versions.
 206  */
 207
 208 extern class_node *class_union(class_node */*l*/, class_node */*r*/);
 209
 210 /* --- @class_diff@ --- *
 211  *
 212  * Arguments:   @class_node *l@ = left argument
 213  *              @class_node *r@ = right argument
 214  *
 215  * Returns:     A class node representing the difference of the two classes.
 216  *
 217  * Use:         Performs the set difference operation on classes.  If the
 218  *              types don't match, then a null pointer is returned.  Both
 219  *              @l@ and @r@ may be modified, and will be decremented before
 220  *              they get returned to you.  If you don't want that to happen,
 221  *              ensure that you've claimed a reference to the original
 222  *              versions.
 223  */
 224
 225 extern class_node *class_diff(class_node */*l*/, class_node */*r*/);
 226
 227 /* --- @class_isect@ --- *
 228  *
 229  * Arguments:   @class_node *l@ = left argument
 230  *              @class_node *r@ = right argument
 231  *
 232  * Returns:     A class node representing the intersection of the two
 233  *              classes.
 234  *
 235  * Use:         Performs the intersecion operation on classes.  If the types
 236  *              don't match, then a null pointer is returned.  Both @l@ and
 237  *              @r@ may be modified, and will be decremented before they get
 238  *              returned to you.  If you don't want that to happen, ensure
 239  *              that you've claimed a reference to the original versions.
 240  */
 241
 242 extern class_node *class_isect(class_node */*l*/, class_node */*r*/);
 243
 244 /* --- @class_addUser@ --- *
 245  *
 246  * Arguments:   @class_node *c@ = pointer to a class node (may be null)
 247  *              @uid_t u@ = user id number
 248  *
 249  * Returns:     Pointer to the combined node.
 250  *
 251  * Use:         Adds a user to a node, maybe hashifying it.
 252  */
 253
 254 extern class_node *class_addUser(class_node */*c*/, uid_t /*u*/);
 255
 256 /* --- @class_addString@ --- *
 257  *
 258  * Arguments:   @class_node *c@ = pointer to a class node (may be null)
 259  *              @const char *s@ = pointer to a string
 260  *
 261  * Returns:     Pointer to the combined node.
 262  *
 263  * Use:         Adds a user to a node, maybe hashifying it.
 264  */
 265
 266 extern class_node *class_addString(class_node */*c*/, const char */*s*/);
 267
 268 /* --- @class_matchUser@ --- *
 269  *
 270  * Arguments:   @class_node *c@ = pointer to root class node
 271  *              @uid_t u@ = user id number
 272  *
 273  * Returns:     Nonzero if it matches, zero if it doesn't.
 274  *
 275  * Use:         Determines whether a user is matched by a class.  Assumes
 276  *              that the types are correct.
 277  */
 278
 279 extern int class_matchUser(class_node */*c*/, uid_t /*u*/);
 280
 281 /* --- @class_matchCommand@ --- *
 282  *
 283  * Arguments:   @class_node *c@ = pointer to root class node
 284  *              @const char *s@ = pointer to a string
 285  *
 286  * Returns:     Nonzero if it matches, zero if it doesn't.
 287  *
 288  * Use:         Determines whether a string is matched by a class.  Assumes
 289  *              that the types are correct.
 290  */
 291
 292 extern int class_matchCommand(class_node */*c*/, const char */*s*/);
 293
 294 /* --- @class_matchHost@ --- *
 295  *
 296  * Arguments:   @class_node *c@ = pointer to root class node
 297  *              @struct in_addr a@ = IP address to match
 298  *
 299  * Returns:     Nonzero if it matches, zero if it doesn't.
 300  *
 301  * Use:         Determines whether a host matches a host class.  Assumes
 302  *              that the types are correct.  The actual mechanism is a bit
 303  *              odd here, but I think this is the Right Thing.  At each stage
 304  *              I try to match %%@/all/%% of the possible names for the host.
 305  *              Thus host `splat' with address 1.2.3.4 would fail to match
 306  *              the class "1.2.*" - "splat".  This seems to be what the
 307  *              author intuitively expects.  It's just a bit weird.
 308  */
 309
 310 extern int class_matchHost(class_node */*c*/, struct in_addr /*a*/);
 311
 312 /* --- @class_dump@ --- *
 313  *
 314  * Argumemnts:  @class_node *c@ = pointer to root node
 315  *              @int indent@ = indent depth
 316  *
 317  * Returns:     ---
 318  *
 319  * Use:         Dumps a class to the trace output.
 320  */
 321
 322 extern void class_dump(class_node */*c*/, int /*indent*/);
 323
 324 /*----- That's all, folks -------------------------------------------------*/
 325
 326 #ifdef __cplusplus
 327   }
 328 #endif
 329
 330 #endif
 331